Billing

Create draft invoice or add to next bill

Requires write:billing. Creates a one-off invoice as a draft for a customer, from one-time products (default or chosen price, or a custom amount) and/or custom lines (description + amountCents), with an optional car per line, due date and memo. Nothing is sent or charged; sending is a separate action, and staff can also finish it at dashboardUrl. Tax and processing fees follow the facility’s settings. With billingOption: "next_bill" no invoice is created: the lines are added to the customer’s next monthly plan bill and charged with it (409 no_eligible_plan when there is no active monthly plan).

POST

api

billing

invoices

Create draft invoice or add to next bill

curl --request POST \
  --url https://www.carstoragesoftware.com/api/v1/billing/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "items": [
    {
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "priceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "description": "<string>",
      "amountCents": 5000000,
      "quantity": 50,
      "carId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "dueDate": "<string>",
  "memo": "<string>",
  "subscriptionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "addOnsGetPlanDiscount": true,
  "idempotencyKey": "<string>",
  "confirmedLargeAmount": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    items: [
      {
        productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        priceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        description: '<string>',
        amountCents: 5000000,
        quantity: 50,
        carId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
      }
    ],
    dueDate: '<string>',
    memo: '<string>',
    subscriptionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    addOnsGetPlanDiscount: true,
    idempotencyKey: '<string>',
    confirmedLargeAmount: true
  })
};

fetch('https://www.carstoragesoftware.com/api/v1/billing/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://www.carstoragesoftware.com/api/v1/billing/invoices"

payload = {
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "items": [
        {
            "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "priceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "description": "<string>",
            "amountCents": 5000000,
            "quantity": 50,
            "carId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
    ],
    "dueDate": "<string>",
    "memo": "<string>",
    "subscriptionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "addOnsGetPlanDiscount": True,
    "idempotencyKey": "<string>",
    "confirmedLargeAmount": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "<string>",
    "number": "<string>",
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "<string>",
    "currency": "<string>",
    "totalCents": 123,
    "amountDueCents": 123,
    "amountPaidCents": 123,
    "amountRemainingCents": 123,
    "dueDate": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "paidAt": "2023-11-07T05:31:56Z",
    "hostedInvoiceUrl": "<string>",
    "subscriptionId": "<string>",
    "dashboardUrl": "<string>",
    "lines": [
      {
        "description": "<string>",
        "amountCents": 123,
        "quantity": 123
      }
    ]
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

Authorizations

Authorization

string

header

required

Team API key from Settings → Integrations. Use Authorization: Bearer <key> or x-api-key.

Body

application/json

customerId

string<uuid>

required

Customer id from list_customers.

items

object[]

required

Required array length: 1 - 25 elements

Show child attributes

dueDate

string

Due date (YYYY-MM-DD). Defaults to the facility's usual terms.

Pattern: ^\d{4}-\d{2}-\d{2}$

memo

string

Note shown on the invoice.

Maximum string length: 500

billingOption

enum<string>

draft (default) creates a draft invoice. next_bill creates no invoice: each line is added to the customer's next monthly plan bill and charged with it (one charge per line). Answers 409 (code: no_eligible_plan) when the customer has no active monthly plan to add to, 409 (code: out_of_stock) when a capped product is sold out, 409 (code: idempotency_conflict) when idempotencyKey was already used for different lines, 409 (code: busy) when the plan's add-ons are being changed (retry shortly), or 409 (code: needs_confirmation) for a large amount sent without confirmedLargeAmount: true. dueDate and memo are ignored.

Available options:

draft,

next_bill

subscriptionId

string<uuid>

next_bill only: the plan to add to (from list_billing_subscriptions). Defaults to the plan that renews soonest.

addOnsGetPlanDiscount

boolean

next_bill only: when the plan has a percent-off discount on the whole plan, whether these lines get it too. Saved on the plan and used for later add-ons. Without an answer, add-ons pay full price.

idempotencyKey

string

next_bill only: send the same key when retrying so each line is stored once.

Required string length: 1 - 200

confirmedLargeAmount

boolean

next_bill only: set to true to add a large amount: any line over the facility's line amount, or lines that take the plan's waiting add-ons over its plan amount (set in Billing settings; $10,000 and $25,000 unless changed, and either can be turned off). Without it such a request stores nothing and answers 409 (code: needs_confirmation, details.largeAmount with the amount and the facility's limit as thresholdCents). Confirm with the person asking, then resend with the same idempotencyKey.

Response

Draft invoice created, or (next_bill) the lines added to the next bill.

Option 1
Option 2

data

object

required

Show child attributes

Create draft invoice or add to next bill

curl --request POST \
  --url https://www.carstoragesoftware.com/api/v1/billing/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "items": [
    {
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "priceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "description": "<string>",
      "amountCents": 5000000,
      "quantity": 50,
      "carId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "dueDate": "<string>",
  "memo": "<string>",
  "subscriptionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "addOnsGetPlanDiscount": true,
  "idempotencyKey": "<string>",
  "confirmedLargeAmount": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customerId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    items: [
      {
        productId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        priceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        description: '<string>',
        amountCents: 5000000,
        quantity: 50,
        carId: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
      }
    ],
    dueDate: '<string>',
    memo: '<string>',
    subscriptionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    addOnsGetPlanDiscount: true,
    idempotencyKey: '<string>',
    confirmedLargeAmount: true
  })
};

fetch('https://www.carstoragesoftware.com/api/v1/billing/invoices', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://www.carstoragesoftware.com/api/v1/billing/invoices"

payload = {
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "items": [
        {
            "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "priceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "description": "<string>",
            "amountCents": 5000000,
            "quantity": 50,
            "carId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
    ],
    "dueDate": "<string>",
    "memo": "<string>",
    "subscriptionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "addOnsGetPlanDiscount": True,
    "idempotencyKey": "<string>",
    "confirmedLargeAmount": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "<string>",
    "number": "<string>",
    "customerId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "<string>",
    "currency": "<string>",
    "totalCents": 123,
    "amountDueCents": 123,
    "amountPaidCents": 123,
    "amountRemainingCents": 123,
    "dueDate": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "paidAt": "2023-11-07T05:31:56Z",
    "hostedInvoiceUrl": "<string>",
    "subscriptionId": "<string>",
    "dashboardUrl": "<string>",
    "lines": [
      {
        "description": "<string>",
        "amountCents": 123,
        "quantity": 123
      }
    ]
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

{
  "error": "<string>",
  "code": "<string>",
  "details": null
}

Get started

Cars

Customers

Contacts

Locations

Parking

Event types

Appointments

Billing

Communications

Marketing

Create draft invoice or add to next bill

Authorizations

Body

Response