Create Client Invoice

Create a new draft client invoice. Tax is calculated automatically.

Scopes: client_invoices:write

POST /v1/client-invoices

Create Client Invoice

cURL

curl --request POST \
  --url https://api.spairehq.com/v1/client-invoices/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "currency": "<string>",
  "line_items": [
    {
      "description": "<string>",
      "unit_amount": 2,
      "quantity": 1
    }
  ],
  "due_date": "2023-12-25",
  "memo": "<string>",
  "po_number": "<string>",
  "on_behalf_of_label": "<string>",
  "discount_amount": 0,
  "discount_label": "<string>",
  "include_payment_link": true,
  "show_logo": true,
  "show_mor_attribution": true,
  "user_metadata": {}
}
'

201

{
  "id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "modified_at": "2023-11-07T05:31:56Z",
  "organization_id": "<string>",
  "customer_id": "<string>",
  "stripe_invoice_id": "<string>",
  "currency": "<string>",
  "subtotal_amount": 123,
  "discount_amount": 123,
  "tax_amount": 123,
  "total_amount": 123,
  "memo": "<string>",
  "po_number": "<string>",
  "due_date": "2023-12-25",
  "on_behalf_of_label": "<string>",
  "discount_label": "<string>",
  "include_payment_link": true,
  "show_logo": true,
  "show_mor_attribution": true,
  "stripe_hosted_invoice_url": "<string>",
  "invoice_pdf_url": "<string>",
  "checkout_link": "<string>",
  "user_metadata": {},
  "order_id": "<string>",
  "line_items": [
    {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "client_invoice_id": "<string>",
      "stripe_invoice_item_id": "<string>",
      "description": "<string>",
      "quantity": 123,
      "unit_amount": 123,
      "currency": "<string>",
      "amount": 123,
      "tax_amount": 123
    }
  ]
}

Authorizations

patoat

Authorization · string · header · required

You can generate a Personal Access Token from your settings.

Body

application/json

customer_id · string<uuid4> · required

ID of the Spaire customer to invoice.

currency · string · required

ISO 4217 currency code (e.g. 'usd').

Required string length: 3

line_items · ClientInvoiceLineItemCreate · object[] · required

Invoice line items. At least one required.

Minimum array length: 1

Show child attributes

due_date · string<date> | null

Payment due date. Determines days_until_due on the Stripe invoice.

memo · string | null

Internal memo / invoice description.

po_number · string | null

Purchase order number.

Maximum string length: 64

on_behalf_of_label · string | null

Name shown in 'on behalf of' display on the invoice. Defaults to the organization name.

discount_amount · integer · default: 0

Flat discount amount in the smallest currency unit (e.g. cents). Applied before tax.

Required range: x >= 0

discount_label · string | null

Label shown for the discount line on the invoice (e.g. 'Promo code').

include_payment_link · boolean · default: true

Whether to include a hosted payment link in the invoice email.

show_logo · boolean · default: true

Whether to show the organization logo on the PDF.

show_mor_attribution · boolean · default: true

Whether to show 'via spaire' label under the logo.

user_metadata · User Metadata · object

Arbitrary key-value metadata to attach to the invoice.

Response

201

application/json

Successful Response

id · string<uuid4> · required

The ID of the object.

created_at · string<date-time> · required

Creation timestamp of the object.

modified_at · string<date-time> | null · required

Last modification timestamp of the object.

organization_id · string<uuid4> · required

customer_id · string<uuid4> · required

stripe_invoice_id · string | null · required

status · enum<string> · required

Available options: draft, open, paid, void, uncollectible

currency · string · required

subtotal_amount · integer · required

discount_amount · integer · required

tax_amount · integer · required

total_amount · integer · required

memo · string | null · required

po_number · string | null · required

due_date · string<date> | null · required

on_behalf_of_label · string | null · required

discount_label · string | null · required

include_payment_link · boolean · required

show_logo · boolean · required

show_mor_attribution · boolean · required

stripe_hosted_invoice_url · string | null · required

invoice_pdf_url · string | null · required

checkout_link · string | null · required

user_metadata · User Metadata · object · required

order_id · string<uuid4> | null · required

line_items · ClientInvoiceLineItemSchema · object[]

Show child attributes