Create a bill

POST

bills

Create a bill

curl --request POST \
  --url https://api.slash.com/v2/bills \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'x-legal-entity: <x-legal-entity>' \
  --data '
{
  "vendorContactId": "le_c_2rj4l7hmrrrcv",
  "destinationId": "le_contact_destination_2rj4l7hmrrrcv",
  "invoiceNumber": "INV-4471",
  "invoiceDate": "2026-09-01",
  "dueDate": "2026-10-01",
  "lineItems": [
    {
      "name": "Hosting",
      "quantity": 1,
      "unitAmount": {
        "amount": 120000,
        "currency": "USD"
      }
    },
    {
      "name": "Support hours",
      "quantity": 2.5,
      "unitAmount": {
        "amount": 15000,
        "currency": "USD"
      }
    }
  ],
  "tax": {
    "amount": 9800,
    "currency": "USD"
  },
  "documentIds": [
    "st_2rj4l7hmrrrcv"
  ],
  "notes": "September hosting"
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'x-legal-entity': '<x-legal-entity>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    vendorContactId: 'le_c_2rj4l7hmrrrcv',
    destinationId: 'le_contact_destination_2rj4l7hmrrrcv',
    invoiceNumber: 'INV-4471',
    invoiceDate: '2026-09-01',
    dueDate: '2026-10-01',
    lineItems: [
      {name: 'Hosting', quantity: 1, unitAmount: {amount: 120000, currency: 'USD'}},
      {
        name: 'Support hours',
        quantity: 2.5,
        unitAmount: {amount: 15000, currency: 'USD'}
      }
    ],
    tax: {amount: 9800, currency: 'USD'},
    documentIds: ['st_2rj4l7hmrrrcv'],
    notes: 'September hosting'
  })
};

fetch('https://api.slash.com/v2/bills', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.slash.com/v2/bills"

payload = {
    "vendorContactId": "le_c_2rj4l7hmrrrcv",
    "destinationId": "le_contact_destination_2rj4l7hmrrrcv",
    "invoiceNumber": "INV-4471",
    "invoiceDate": "2026-09-01",
    "dueDate": "2026-10-01",
    "lineItems": [
        {
            "name": "Hosting",
            "quantity": 1,
            "unitAmount": {
                "amount": 120000,
                "currency": "USD"
            }
        },
        {
            "name": "Support hours",
            "quantity": 2.5,
            "unitAmount": {
                "amount": 15000,
                "currency": "USD"
            }
        }
    ],
    "tax": {
        "amount": 9800,
        "currency": "USD"
    },
    "documentIds": ["st_2rj4l7hmrrrcv"],
    "notes": "September hosting"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "x-legal-entity": "<x-legal-entity>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.slash.com/v2/bills"

	payload := strings.NewReader("{\n  \"vendorContactId\": \"le_c_2rj4l7hmrrrcv\",\n  \"destinationId\": \"le_contact_destination_2rj4l7hmrrrcv\",\n  \"invoiceNumber\": \"INV-4471\",\n  \"invoiceDate\": \"2026-09-01\",\n  \"dueDate\": \"2026-10-01\",\n  \"lineItems\": [\n    {\n      \"name\": \"Hosting\",\n      \"quantity\": 1,\n      \"unitAmount\": {\n        \"amount\": 120000,\n        \"currency\": \"USD\"\n      }\n    },\n    {\n      \"name\": \"Support hours\",\n      \"quantity\": 2.5,\n      \"unitAmount\": {\n        \"amount\": 15000,\n        \"currency\": \"USD\"\n      }\n    }\n  ],\n  \"tax\": {\n    \"amount\": 9800,\n    \"currency\": \"USD\"\n  },\n  \"documentIds\": [\n    \"st_2rj4l7hmrrrcv\"\n  ],\n  \"notes\": \"September hosting\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("x-legal-entity", "<x-legal-entity>")
	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "bill_2rj4l7hmrrrcv",
  "status": "draft",
  "source": "api",
  "vendorContactId": "le_c_2rj4l7hmrrrcv",
  "destinationId": "le_contact_destination_2rj4l7hmrrrcv",
  "ownerUserId": "u_2rj4l7hmrrrcv",
  "invoiceNumber": "INV-4471",
  "invoiceDate": "2026-09-01",
  "dueDate": "2026-10-01",
  "currency": "USD",
  "amounts": {
    "total": {
      "amount": 167300,
      "currency": "USD"
    },
    "tax": {
      "amount": 9800,
      "currency": "USD"
    },
    "discount": {
      "amount": 0,
      "currency": "USD"
    },
    "outstanding": {
      "amount": 167300,
      "currency": "USD"
    }
  },
  "lineItems": [
    {
      "id": "bill_line_item_2rj4l7hmrrrcv",
      "name": "Hosting",
      "quantity": 1,
      "unitAmount": {
        "amount": 120000,
        "currency": "USD"
      },
      "total": {
        "amount": 120000,
        "currency": "USD"
      }
    },
    {
      "id": "bill_line_item_3sk5m8inssscw",
      "name": "Support hours",
      "quantity": 2.5,
      "unitAmount": {
        "amount": 15000,
        "currency": "USD"
      },
      "total": {
        "amount": 37500,
        "currency": "USD"
      }
    }
  ],
  "documentIds": [
    "st_2rj4l7hmrrrcv"
  ],
  "payments": [],
  "notes": "September hosting",
  "createdAt": "2026-09-19T14:05:22.000Z"
}

Authorizations

X-API-Key

string

header

required

User API key authentication. Create a key under Settings → API keys in the Slash dashboard (https://app.slash.com/global-settings/api-keys) and send the x-legal-entity header naming the legal entity to act on with every request. Keys scoped to a legal entity are rejected with 403 user_api_key_required.

Headers

X-Idempotency-Key

string

required

Unique caller-generated key for one create request. Once an authenticated, schema-valid request reaches the operation, the key is permanently consumed for that operation and legal entity whether the operation succeeds or fails. Reusing it in that scope returns 409 and never replays a response, unlike API v1, which replays the original response for a matching key.

Required string length: 1 - 255

x-legal-entity

string

required

The legal entity to act on. Required on every request; a user API key can act on any legal entity its user has access to.

Pattern: ^le_[a-zA-Z0-9]+$

Body

application/json

A new bill in draft. Every money field must use the same currency.

lineItems

BillLineItemCreate · object[]

required

At least one line. The bill's currency is the lines' currency, and the total is the sum of line totals plus tax minus discount.

Minimum array length: 1

Hide child attributes

lineItems.name

string

required

What the line is for.

Required string length: 1 - 255

Example:

"Hosting"

lineItems.quantity

number

required

Number of units greater than zero. Fractional quantities are allowed.

Example:

1

lineItems.unitAmount

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

lineItems.unitAmount.amount

integer

required

Amount in the currency's minor units.

lineItems.unitAmount.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

vendorContactId

string

The vendor: any contact on the legal entity that isn't archived, usually one with recipientType: vendor. Create one with POST /v2/contacts.

Example:

"le_c_2rj4l7hmrrrcv"

destinationId

string

The destination the bill should be paid to. Must belong to vendorContactId when both are given.

Example:

"le_contact_destination_2rj4l7hmrrrcv"

ownerUserId

string

The user responsible for the bill. Defaults to the user behind the API key.

Example:

"u_2rj4l7hmrrrcv"

invoiceNumber

string

The vendor's invoice number.

Maximum string length: 255

Example:

"INV-4471"

invoiceDate

string<date>

Invoice date as YYYY-MM-DD.

Example:

"2026-09-01"

dueDate

string<date>

Due date as YYYY-MM-DD.

Example:

"2026-10-01"

tax

object

Tax added to the line totals, in the bill's currency.

Hide child attributes

tax.amount

integer

required

Amount in the currency's minor units.

Required range: x >= 0

Example:

800

tax.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

Example:

"USD"

discount

object

Discount taken off the line totals, in the bill's currency.

Hide child attributes

discount.amount

integer

required

Amount in the currency's minor units.

Required range: x >= 0

Example:

500

discount.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

Example:

"USD"

documentIds

string[]

Documents uploaded with purpose bill_invoice.

Maximum array length: 20

notes

string

Free-text notes visible to your organization.

Maximum string length: 5000

Response

The created bill.

Money your legal entity owes a vendor. status and amounts.outstanding are derived from the bill's payments and cannot be set directly.

string

required

Bill id with the bill_ prefix.

Example:

"bill_2rj4l7hmrrrcv"

status

enum<string>

required

Derived from the bill's payments. draft until a payment exists; pending_approval while a payment awaits approval; rejected when the latest approval was rejected; scheduled when a payment is scheduled; payment_pending while a payment is in flight; partially_paid when settled payments cover part of the total; paid when they cover all of it; payment_failed when the latest payment failed or was returned.

Available options:

draft,

pending_approval,

rejected,

scheduled,

payment_pending,

paid,

payment_failed,

partially_paid

source

enum<string>

required

How the bill entered Slash. api for bills created through this API, manual for the dashboard, email for the accounts-payable inbox, carrier_account for bills pulled from a connected carrier portal. Carrier bills are read-only over the API.

Available options:

manual,

email,

carrier_account,

api

currency

string

required

Uppercase ISO 4217 currency code shared by every amount on the bill.

Pattern: ^[A-Z]{3}$

Example:

"USD"

amounts

object

required

Every amount is in currency, in minor units.

Hide child attributes

amounts.total

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

amounts.total.amount

integer

required

Amount in the currency's minor units.

amounts.total.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

amounts.tax

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

amounts.tax.amount

integer

required

Amount in the currency's minor units.

amounts.tax.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

amounts.discount

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

amounts.discount.amount

integer

required

Amount in the currency's minor units.

amounts.discount.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

amounts.outstanding

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

amounts.outstanding.amount

integer

required

Amount in the currency's minor units.

amounts.outstanding.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

lineItems

BillLineItem · object[]

required

Line items in display order.

Hide child attributes

lineItems.id

string

required

Line item id with the bill_line_item_ prefix.

Example:

"bill_line_item_2rj4l7hmrrrcv"

lineItems.name

string

required

What the line is for, as printed on the invoice.

Example:

"Hosting"

lineItems.quantity

number

required

Number of units. Fractional quantities are allowed.

Example:

1

lineItems.unitAmount

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

lineItems.unitAmount.amount

integer

required

Amount in the currency's minor units.

lineItems.unitAmount.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

lineItems.total

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

lineItems.total.amount

integer

required

Amount in the currency's minor units.

lineItems.total.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

documentIds

string[]

required

Documents attached to the bill, readable at GET /v2/documents/{documentId}.

payments

BillPayment · object[]

required

Payments linked to the bill, oldest first.

Hide child attributes

payments.id

string

required

Payment link id with the bill_payment_ prefix. Unlink the payment with DELETE /v2/bills/{billId}/payments/{paymentId}.

Example:

"bill_payment_2rj4l7hmrrrcv"

payments.status

enum<string>

required

Coarse transaction state.

Available options:

pending,

posted,

failed

payments.detailedStatus

enum<string>

required

Exact transaction lifecycle state across every category.

Available options:

pending,

pending_destination,

pending_approval,

in_review,

scheduled,

canceled,

failed,

settled,

declined,

refund,

reversed,

returned,

dispute

payments.amount

Money · object

required

A signed monetary amount expressed in minor units.

Hide child attributes

payments.amount.amount

integer

required

Amount in the currency's minor units.

payments.amount.currency

string

required

Uppercase ISO 4217 currency code.

Pattern: ^[A-Z]{3}$

payments.createdAt

string<date-time>

required

When the payment was linked to the bill.

payments.transferId

string

Id of the transfer that pays the bill, with the transfer_intent_ prefix, readable at GET /v2/transfers/{transferId}. Absent for payments that are not yet a transfer (a scheduled payment whose transfer has not been constructed) or that were made outside the transfer rails.

Example:

"transfer_intent_2rj4l7hmrrrcv"

payments.transactionId

string

Id of the transaction that moved the money, with the agg_tx_ prefix, readable at GET /v2/transactions/{transactionId}. For a card purchase it's the card transaction. Absent when the payment's only transactions are ones the transactions API doesn't return, such as a rejected or canceled approval request.

Example:

"agg_tx_2rj4l7hmrrrcv"

createdAt

string<date-time>

required

When the bill was created.

vendorContactId

string

The vendor contact, readable at GET /v2/contacts/{contactId}.

Example:

"le_c_2rj4l7hmrrrcv"

destinationId

string

The destination the bill is expected to be paid to, readable at GET /v2/destinations/{destinationId}.

Example:

"le_contact_destination_2rj4l7hmrrrcv"

ownerUserId

string

The user responsible for the bill. Absent for bills that arrived by email and have not been assigned.

Example:

"u_2rj4l7hmrrrcv"

invoiceNumber

string

The vendor's invoice number.

Example:

"INV-4471"

invoiceDate

string<date>

Invoice date as YYYY-MM-DD.

Example:

"2026-09-01"

dueDate

string<date>

Due date as YYYY-MM-DD.

Example:

"2026-10-01"

notes

string

Free-text notes visible to your organization.

⌘I

Create a bill

curl --request POST \
  --url https://api.slash.com/v2/bills \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --header 'x-legal-entity: <x-legal-entity>' \
  --data '
{
  "vendorContactId": "le_c_2rj4l7hmrrrcv",
  "destinationId": "le_contact_destination_2rj4l7hmrrrcv",
  "invoiceNumber": "INV-4471",
  "invoiceDate": "2026-09-01",
  "dueDate": "2026-10-01",
  "lineItems": [
    {
      "name": "Hosting",
      "quantity": 1,
      "unitAmount": {
        "amount": 120000,
        "currency": "USD"
      }
    },
    {
      "name": "Support hours",
      "quantity": 2.5,
      "unitAmount": {
        "amount": 15000,
        "currency": "USD"
      }
    }
  ],
  "tax": {
    "amount": 9800,
    "currency": "USD"
  },
  "documentIds": [
    "st_2rj4l7hmrrrcv"
  ],
  "notes": "September hosting"
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Idempotency-Key': '<x-idempotency-key>',
    'x-legal-entity': '<x-legal-entity>',
    'X-API-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    vendorContactId: 'le_c_2rj4l7hmrrrcv',
    destinationId: 'le_contact_destination_2rj4l7hmrrrcv',
    invoiceNumber: 'INV-4471',
    invoiceDate: '2026-09-01',
    dueDate: '2026-10-01',
    lineItems: [
      {name: 'Hosting', quantity: 1, unitAmount: {amount: 120000, currency: 'USD'}},
      {
        name: 'Support hours',
        quantity: 2.5,
        unitAmount: {amount: 15000, currency: 'USD'}
      }
    ],
    tax: {amount: 9800, currency: 'USD'},
    documentIds: ['st_2rj4l7hmrrrcv'],
    notes: 'September hosting'
  })
};

fetch('https://api.slash.com/v2/bills', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.slash.com/v2/bills"

payload = {
    "vendorContactId": "le_c_2rj4l7hmrrrcv",
    "destinationId": "le_contact_destination_2rj4l7hmrrrcv",
    "invoiceNumber": "INV-4471",
    "invoiceDate": "2026-09-01",
    "dueDate": "2026-10-01",
    "lineItems": [
        {
            "name": "Hosting",
            "quantity": 1,
            "unitAmount": {
                "amount": 120000,
                "currency": "USD"
            }
        },
        {
            "name": "Support hours",
            "quantity": 2.5,
            "unitAmount": {
                "amount": 15000,
                "currency": "USD"
            }
        }
    ],
    "tax": {
        "amount": 9800,
        "currency": "USD"
    },
    "documentIds": ["st_2rj4l7hmrrrcv"],
    "notes": "September hosting"
}
headers = {
    "X-Idempotency-Key": "<x-idempotency-key>",
    "x-legal-entity": "<x-legal-entity>",
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.slash.com/v2/bills"

	payload := strings.NewReader("{\n  \"vendorContactId\": \"le_c_2rj4l7hmrrrcv\",\n  \"destinationId\": \"le_contact_destination_2rj4l7hmrrrcv\",\n  \"invoiceNumber\": \"INV-4471\",\n  \"invoiceDate\": \"2026-09-01\",\n  \"dueDate\": \"2026-10-01\",\n  \"lineItems\": [\n    {\n      \"name\": \"Hosting\",\n      \"quantity\": 1,\n      \"unitAmount\": {\n        \"amount\": 120000,\n        \"currency\": \"USD\"\n      }\n    },\n    {\n      \"name\": \"Support hours\",\n      \"quantity\": 2.5,\n      \"unitAmount\": {\n        \"amount\": 15000,\n        \"currency\": \"USD\"\n      }\n    }\n  ],\n  \"tax\": {\n    \"amount\": 9800,\n    \"currency\": \"USD\"\n  },\n  \"documentIds\": [\n    \"st_2rj4l7hmrrrcv\"\n  ],\n  \"notes\": \"September hosting\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
	req.Header.Add("x-legal-entity", "<x-legal-entity>")
	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": "bill_2rj4l7hmrrrcv",
  "status": "draft",
  "source": "api",
  "vendorContactId": "le_c_2rj4l7hmrrrcv",
  "destinationId": "le_contact_destination_2rj4l7hmrrrcv",
  "ownerUserId": "u_2rj4l7hmrrrcv",
  "invoiceNumber": "INV-4471",
  "invoiceDate": "2026-09-01",
  "dueDate": "2026-10-01",
  "currency": "USD",
  "amounts": {
    "total": {
      "amount": 167300,
      "currency": "USD"
    },
    "tax": {
      "amount": 9800,
      "currency": "USD"
    },
    "discount": {
      "amount": 0,
      "currency": "USD"
    },
    "outstanding": {
      "amount": 167300,
      "currency": "USD"
    }
  },
  "lineItems": [
    {
      "id": "bill_line_item_2rj4l7hmrrrcv",
      "name": "Hosting",
      "quantity": 1,
      "unitAmount": {
        "amount": 120000,
        "currency": "USD"
      },
      "total": {
        "amount": 120000,
        "currency": "USD"
      }
    },
    {
      "id": "bill_line_item_3sk5m8inssscw",
      "name": "Support hours",
      "quantity": 2.5,
      "unitAmount": {
        "amount": 15000,
        "currency": "USD"
      },
      "total": {
        "amount": 37500,
        "currency": "USD"
      }
    }
  ],
  "documentIds": [
    "st_2rj4l7hmrrrcv"
  ],
  "payments": [],
  "notes": "September hosting",
  "createdAt": "2026-09-19T14:05:22.000Z"
}

Accounts

Virtual accounts

Contacts

Transfers

Transactions

Documents

Bills

Accounting

Create a bill

Authorizations

Headers

Body

Response