Billy API v2 Documentation

Billy's new API is a JSON-based REST API. Our webapp uses the exact same API - which is your guarantee that the API will always support full functionality, and will generally be nice to work with. We take our own medicine!

If you have any questions or feedback (we love feedback!), please don't hesitate to write us at dev@billy.dk.

Table of Contents

• Endpoint
• Authentication
• Conventions
• Relationships
• Paging
• Filtering
• Sorting
• Code examples
• Use case examples
• Resource documentation

Endpoint

The API is located at https://api.billysbilling.com/v2.

All requests must use SSL.

Authentication

We currently support two authentication methods with the API.

OAuth access tokens

Here's how to obtain an access token for your company:

• Log into your account on app.billysbilling.com.
• Go to Settings -> Access tokens.
• Click Create access token.
• Enter a descriptive name for your token, so you can easily identify it later. Then hit the Save button.
• Hover over the newly-generated access token and click the magnifier icon to show it clearly.
• The token will now be selected in a text field, inside a lightbox.

All you have to do now is put this token in a X-Access-Token header. See Code examples for a complete example.

The tokens you create under Settings -> Access tokens are tied to that company only. If you have multiple companies, you'll need a separate token for each one. Tokens are permanent - the don't expire.

We plan to support a 3-legged OAuth solution eventually.

HTTP basic auth

You can use your normal email and password for authentication HTTP Basic Auth. You can try it right now, if you like. Just navigate to https://api.billysbilling.com/v2/user. Enter your email and password in the browser's credentials form, and you'll see your user as a JSON document.

Conventions

Billy's API is very consistent; we use the same conventions for all resources. Generally speaking, there are 5 ways to interact with a resource: Get one item, list, create, update and delete.

A resource is always accessed through its pluralized name. For example, you can access invoices through /v2/invoices.

In the examples that follow, we'll use the invoices resource - but the exact same pattern applies to all resources.

Getting a single record

When getting a single record, you should use GET /v2/invoices/:id (where :id denotes a dynamic slug, and should be replaced by a real invoice ID). The response will be a JSON document with a root key named after the singular name containing the requested record. Invoice example:

Listing a resource

Use GET /v2/invoices. The response will be a JSON document with a root key named after the pluralized designation and containing an array of found records. Invoice example:

Creating a record

Use POST /v2/invoices. The request body should be a JSON document containing a single root key named after the singular name, and should be a hash of record properties. Invoice example:

See more about the response body in the section Responses to create/update/delete. You can get the ID of the newly created record by getting invoices.0.id in the returned JSON document.

Updating a record

Use PUT /v2/invoices/:id. The request body should be a JSON document containing a single root key named after the singular name, and should be a hash of record properties. The hash does not need to include the record's ID - if it does, though, it must be exactly the same ID you used in the URL. You can't change a record's ID. Invoice example:

Only properties that you set in the invoice hash will be updated. Properties that are left out will be considered as if they are the same. So if all you need to do is to update the contactMessage property, then you don't need to include any other properties.

The response works the same as with a POST request.

Deleting a record

Use DELETE /v2/invoices/:id. The request should not have a body.

DELETE requests are idempotent, meaning that if you try to DELETE the same record more than once (or delete any other non-existing ID), you will still receive a 200 OK response.

See more about the response body in the section 'Responses to create/update/delete requests'.

Responses to create/update/delete requests

When you make POST, PUT, PATCH or DELETE requests to the API, the response will always include all records that changed because of the request. The record you created/updated will of course be included. Example: When you create an invoiceLine for an existing invoice, the amount field on the invoice will also be changed. So a POST /v2/invoiceLines would return something like:

The IDs of deleted records will be accessible through the meta.deletedRecords property. Example: When requesting DELETE /v2/invoices/1234, the response will be:

Note that some PUT requests may delete records, too - for example, when you overwrite a record's has-many relationship using an embedded array of child records.

Relationships

The API is smart about relationships. Many resources have relationships, and we distinguish between two kinds of relationships:

• Belongs-to: A record of resource A has an ID that points to a record of resource B. Example: invoice records have a contactId property which points to a contact record.
• Has-many: A record of resource A has zero or more records of resource B that point to it. Example: invoice records have zero or more invoiceLine records that have an invoiceId property, which points back. A has-many relationship always implies a belongs-to relationship on the inverse resource.

Normally, when you GET a resource that has relationships, the belongs-to relationship will be presented as the name of the property, suffixed with Id and containing the ID. If you GET /v2/invoices/123 and it responds with a "contactId": "987", you can get the contact by requesting GET /v2/contacts/987. Has-many relationships won't be in the request, by default.

Requesting sideloaded or embedded records

You can include relationships by adding an include parameter to your GET request. The value of the include parameter should be in the form resource.property:mode[,resource.property:mode,...], where resource is the name of a resource, property is the name of a property of that resource, and mode is either sideload (default if the : part is omitted) or embed. You can include multiple relationships by separating them with ,.

Example: You can load invoices with its invoiceLines embedded, its contacts sideloaded, and the contact's country embedded by doing GET /invoices?include=invoice.lines:embed,invoice.contact:sideload,contact.country:embed. The response will be something like:

When sideloading belongs-to relationships, the name of the key is the singular name of the resource, suffixed with Id (like the default behavior), and each sideloaded record can be found in a root key named after the plural name of the belongs-to inverse resource. It's recommended to sideload records instead of embedding, to avoid duplication (each belongs-to record is only included in the response once).

When embedding belongs-to relationships, the name of the key is the singular name of the resource, for example contact - and it contains all the record's properties.

When sideloading has-many relationships, all the child IDs are included as an array of strings in the parent record, in a key named after the relationship's name (not the inverse resource), suffixed with Ids.

When embedding has-many relationships, all the full child records are included as an array of hashes in the parent record, in a key named after the relationship's name (not the inverse resource).

Saving embedded records

Some resources supports saving child records embedded. An example is invoices. A POST /v2/invoices's request body could look like this:

It's advantageous to embed records when possible, as you get fewer round trips to the API, and everything happens as an atomic transaction (either all or no records are saved).

Paging

You can limit long lists of resources using the paging URL params.

To use pages, you can use page and pageSize. For example, to get the second page containing 20 records per page, you would request GET /v2/invoices?page=2&pageSize=20.

pageSize cannot be greater than 1000 (which is also the default if pageSize is omitted).

Whether your results are truncated/paged can be found in the meta.paging key in the response. It will look something like:

Filtering

When listing most resources, you can filter the results by various properties.

Sorting

When listing most resources, you can sort the results using the sortProperty and sortDirection URL params. Each resource only allows sorting by specific properties. Those properties are noted in each resource's documentation. The sortDirection must be either ASC (default) or DESC.

Code examples

PHP

Node.js 8+

First run npm install axios.

Python 3

First run pip3 install requests.

Use case examples

Posting a payment for an invoice

When you want to mark an invoice as paid, you have to create a bank payment which matches the invoice's amount. Let's say you've just created an invoice with ID inv-1234, with a total amount due of $1,200. This is how you would create the payment:

POST https://api.billysbilling.com/v2/bankPayments

cashAccountId is the account that an amount of cashAmount was deposited to/withdrawn from. cashSide: "debit" means a deposit (used for invoices). cashSide: "credit" means a withdrawal (used for bills).

Each item in the associations array is a balance modifier. Since payments can pay different types of models (invoices, bills, etc.), you add the invoice to the payment by using a "reference," which is a type concatenated with a colon, concatenated with an ID; for example, invoice:inv-1234

The payment's currency is determined by the associations. This means that all associations must point to subjects in the same currency. That is, you can't pay a USD invoice together with an EUR invoice. This currency is called subjectCurrency, if you GET the bank payment later from the API. If the subjectCurrency is different from the currency of cashAccount, you also need to set a cashExchangeRate. In this example, we assume that the cashAccount is in USD.

After this call, our example invoice (for $1,200) will be paid, which will be visible through the invoice's isPaid property - which will be true - and its balance property, which will be 0.0.

The organizationId is only necessary if you are using an access token that's tied to a user (rather than a company), or if you are using Basic Auth. You can list your user's companies through GET /v2/user/organizations.

Posting a product with default price(s)

When POSTing to /v2/products, you can embed product prices this way:

POST https://api.billysbilling.com/v2/products

The organizationId is only necessary if you are using an access token that's tied to a user (rather than a company), or if you are using Basic Auth. You can list your user's companies through GET /v2/user/organizations.

Resource Documentation

Following is an extensive list of resources you can interact with.

In addition to the standard resources, there are also a number of "special" routes by which you can interact with the resources - for example, sending an invoice as email. These are not yet documented.

Table of Contents

• accountGroups
• accountNatures
• accounts
• attachments
• balanceModifiers
• bankLineMatches
• bankLines
• bankLineSubjectAssociations
• bankPayments
• billLines
• bills
• cities
• contactBalancePayments
• contactBalancePostings
• contactPersons
• contacts
• countryGroups
• countries
• currencies
• daybookBalanceAccounts
• daybooks
• daybookTransactionLines
• daybookTransactions
• files
• invoiceLateFees
• invoiceLines
• invoiceReminderAssociations
• invoiceReminders
• invoices
• locales
• organizations
• postings
• productPrices
• products
• salesTaxAccounts
• salesTaxMetaFields
• salesTaxPayments
• salesTaxReturns
• salesTaxRules
• salesTaxRulesets
• states
• taxRateDeductionComponents
• taxRates
• transactions
• users
• zipcodes

Resources

/v2/accountGroups

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requirednaturebelongs-to-immutable, requirednamestring-requireddescriptionstring- 

/v2/accountNatures

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesreportTypeenum- namestring- normalBalanceenum- 

/v2/accounts

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requirednamestring-requiredaccountNointeger- descriptionstring- groupbelongs-to-requirednaturebelongs-to-immutable, default: unknownsystemRoleenum- currencybelongs-to-immutabletaxRatebelongs-to- isPaymentEnabledboolean- isBankAccountboolean-immutableisArchivedboolean- bankNamestring-readonlybankRoutingNostring-readonlybankAccountNostring-readonlybankSwiftstring-readonlybankIbanstring-readonly

/v2/attachments

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredcreatedTimedatetime-readonlyownerbelongs-to-reference-immutable, requiredfilebelongs-toThe ID of the file to attach.immutable, requiredpriorityinteger- 

/v2/balanceModifiers

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesmodifierbelongs-to-reference-immutable, requiredsubjectbelongs-to-reference-immutable, requiredamountfloatBalance modifier amount.readonlyentryDatedateDate of balance modifier entryreadonlyrealizedCurrencyDifferencefloat-readonlyisVoidedboolean-readonly

/v2/bankLineMatches

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesaccountbelongs-toThe ID of the account to create the bank line match for.immutable, requireddifferenceTypeenumIf there is a difference, this value determines its type.immutablefeeAccountbelongs-toThe ID of the account to add the bank fee to.immutable, requiredentryDatedate-immutableamountfloat-immutablesideenum-immutableisApprovedbooleanWhether the bank lines and subjects are approved. approvedTimedatetimeTime of approval.readonlylineshas-manyLines for this bank line match. If this parameter is set, any existing lines for this bank line match will be deleted before adding the new ones.readonlysubjectAssociationshas-manySubject associations for the bank line match. If this parameter is set, any existing subject associations for this bank line match will be deleted before adding the new ones.readonly

/v2/bankLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesmatchbelongs-to-requiredaccountbelongs-toThe ID of the account to create the bank line match for.requiredentryDatedate-requireddescriptionstring-requiredamountfloat-requiredsideenum-required

/v2/bankLineSubjectAssociations

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesmatchbelongs-to-requiredsubjectbelongs-to-referenceThe reference of the subject.required

/v2/bankPayments

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredcontactbelongs-toThe contact that all of the associations' subjects belong to. You can omit setting this property if you supply one or more records in associations. It will then default to the contact of the associations' subject.immutable, required, default: unknowncreatedTimedatetimeWhen the payment record was created in the system.readonlyentryDatedateThe date of the transaction.immutable, requiredcashAmountfloatThe amount that was deposited into or withdrawn from cashAccount in the account's currency.immutable, requiredcashSideenumIndicates whether the payment was a deposit (debit) or a withdrawal (credit).immutable, requiredcashAccountbelongs-toThe account that an amount was deposited into or withdrawn from. Must have isPaymentEnabled set to true.immutable, requiredcashExchangeRatefloatThe exchange rate between subjectCurrency and cashAccount's currency. 1 subjectCurrency = cashExchangeRate cashAccountCurrency. Must be set if cashAccount's currency is different than subjectCurrency. Will be ignored and set to 1 if the currencies are the same.immutable, required, default: unknownsubjectCurrencybelongs-toThe currency of what was paid. You can omit setting this property if you supply one or more records in associations. It will then default to the currency of the associations' subject. In case of an overpayment, the overpaid amount will be added to the contact's balance in this currency.immutable, required, default: unknownfeeAmountfloatUsed if the bank or payment provider charged the organization a fee for handling this payment. The fee amount must be positive, and will always be recorded as an expense (i.e., a debit posting on an expense account). feeAmount is in the same currency as cashAccount's currency. The fee is always considered the organization's expense. This means that: - For deposits the subjects' balances will also be offset against the fee, as the customer shouldn't pay for the organization's payment expenses. Example: An invoice of 100 USD will be paid in full by a cashAmount of 95 and a feeAmount of 5. - For withdrawals the subject's balances will not be offset against the fee, as the supplier shouldn't pay for the organization's payment expenses. Example: A bill of 100 USD will be paid in full by a cashAmount of 105 and a feeAmount of 5.immutablefeeAccountbelongs-toThe account to record the fee expense on. Must be an expense account. Must be set if feeAmount is set.immutable, requiredisVoidedbooleanIndicates if the payment has been canceled. You must leave this field blank or set to false for new payments. Once a payment has been canceled by setting this field to true it can't be reinstated ("un-canceled"). associationshas-manyThe subjects this payment involves. The subjects' outstanding balance and isPaid properties will automatically be updated by the API.immutablecontactBalancePostingshas-many-readonly

/v2/billLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesbillbelongs-to-immutable, requiredaccountbelongs-to-requiredtaxRatebelongs-to- descriptionstring-requiredamountfloat-requiredtaxfloat-readonlypriorityinteger- 

/v2/bills

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredtypeenum-immutablecreatedTimedatetime-readonlyapprovedTimedatetime-readonlycontactbelongs-to-immutable, requiredcontactNamestring- entryDatedate-requiredpaymentAccountbelongs-to-immutablepaymentDatedate-immutable, requireddueDatedate- isBareboolean- stateenum-default: "draft"suppliersInvoiceNostring- taxModeenum- voucherNostringVoucher number for the bill amountfloat-readonlytaxfloat-readonlycurrencybelongs-to- exchangeRatefloat- balancefloat-readonlyisPaidboolean-readonlylineDescriptionstring-readonlycreditedBillbelongs-to-immutablecreditNoteshas-many-readonlylineshas-many- attachmentshas-many- balanceModifiershas-manyPayment associations for the bill.readonlysourcestringSource of the bill.readonlysubjectstringOriginal subject of the bill.readonly

/v2/cities

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesnamestring- countystring- statebelongs-to- countrybelongs-to- 

/v2/contactBalancePayments

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredcontactbelongs-toAutomatically set by the API. The contact that all of the associations' subjects belong to.immutable, required, default: unknowncreatedTimedatetime-readonlyentryDatedateThe date that this transaction occurred accounting-wise.immutable, requiredamountfloatThe amount to apply to the subject(s) balance.immutable, requiredsideenumAutomatically set by the API. Indicates: - debit: The payment used a prepayment that a customer made to the company. - credit: The payment used a prepayment that the company made to a vendor.immutable, required, default: unknowncurrencybelongs-toAutomatically set by the API to the currency of the subject(s).immutable, required, default: unknownisVoidedboolean- associationshas-manyThe subjects this payment involves. The subjects' outstanding balance and isPaid properties will automatically be updated by the API.immutable, required

/v2/contactBalancePostings

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotescontactbelongs-to-readonlyoriginatorbelongs-to-reference-readonlycreatedTimedatetime-readonlyentryDatedate-readonlyamountfloat-readonlysideenum-readonlycurrencybelongs-to-readonlyisVoidedboolean-readonly

/v2/contactPersons

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotescontactbelongs-to-immutable, requiredisPrimarybooleanIf contact person is primary for the parent contact. namestringThe name of the contact person. Either name or email must be set.requiredemailstringThe contact person's e-mail. Used to mail invoices to the contact. Either name or email must be set. 

/v2/contacts

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotestypeenumWhether contact is a company or an person. Defaults to companyrequired, default: "company"organizationbelongs-to-immutable, requiredcreatedTimedatetime-readonlynamestringThe name of the contact. Can be either a company name or a person's name.requiredcountrybelongs-toThe contact's home/business country.requiredstreetstringThe contact's street address. citybelongs-toThe contact's city, if finite. cityTextstringThe contact's city, in text form. statebelongs-toThe name of the contact's state, if finite. stateTextstringThe name of the contact's state, in text form. zipcodebelongs-toThe contact's zipcode, if finite. zipcodeTextstringThe contact's zipcode, in text form. contactNostringArbitrary number (or string) that contacts can be referred to by. phonestringThe contact's phone number. faxstringThe contact's fax number. currencybelongs-toDefault currency to use for invoices created for the contact. Has no effect in the API, as currency for invoice always is required. registrationNostringThe contact's EU VAT number, CVR number in Denmark, tax ID (TIN/EIN/SSN) in the US. eanstringThe contact's EAN (European Article Number). localebelongs-toLanguage to use in communications with the contact. The language also decides which language should be used on invoices created for the contact. isCustomerbooleanWhether the contact is regarded as a customer and can have invoices, etc. isSupplierbooleanWhether the contact is regarded as a vendor and can have bills etc. paymentTermsModeenum- paymentTermsDaysinteger-requiredcontactPersonshas-manyYou can add one or more contact persons for the contact. If this parameter is set, any existing contact persons for this contact will be deleted before adding the new ones. accessCodestringUsed to generate the contact's customer portal URL. emailAttachmentDeliveryModeenumWhether to deliver attachments by link to customer portal or with email attachments. isArchivedbooleanWhether the contact is archived. 

/v2/countryGroups

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesnamestring- iconstring- memberCountryIdsstring- 

/v2/countries

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesnamestring- hasStatesboolean- hasFiniteStatesboolean- hasFiniteZipcodesboolean- iconstring- localebelongs-to- 

/v2/currencies

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesnamestring- exchangeRatefloat- 

/v2/daybookBalanceAccounts

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesdaybookbelongs-to-requiredaccountbelongs-to-requiredpriorityinteger-required

/v2/daybooks

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredisTransactionSummaryEnabledboolean-requirednamestringThe name of the daybook.requireddefaultContraAccountbelongs-to- balanceAccountshas-manyBalance accounts to monitor. 

/v2/daybookTransactionLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesdaybookTransactionbelongs-to-immutable, requiredtextstringLine description. accountbelongs-to@id@ of account line is to be applied to. Either @accountId@ or @accountNo@ must be filled in.immutable, requiredtaxRatebelongs-to-immutablecontraAccountbelongs-to@id@ of account line is to be applied against.immutableamountfloatAmount of line.immutable, requiredsideenum"debit" or "credit"immutable, requiredcurrencybelongs-to-immutable, default: unknownpriorityinteger- 

/v2/daybookTransactions

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requireddaybookbelongs-to- createdTimedatetime-readonlyentryDatedateThe transaction entry date in YYYY-MM-DD format.immutable, requiredvoucherNostringA number or a string that identifies this transaction's voucher number, e.g. a bill. descriptionstringDescription of transaction. extendedDescriptionstringExtended/verbose description of transaction. apiTypestringMethod used to make the API call. This is for your notation only. stateenum-default: "draft"priorityinteger- lineshas-manyLines for the transaction. At minimum one line must be supplied.immutableattachmentshas-manyAttachments for the daybook transaction.immutable

/v2/files

Supports: get by id, list, create, bulk save, bulk delete

PropertyTypeDescriptionNotescreatedTimedatetime-readonlyfileNamestring-readonlyfileSizeinteger-readonlyfileTypestring-readonlyisImageboolean-readonlyisPdfboolean-readonlyimageWidthinteger-readonlyimageHeightinteger-readonlydownloadUrlstring-readonly

/v2/invoiceLateFees

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesinvoicebelongs-to-immutable, requiredcreatedTimedatetime-readonlyentryDatedate-immutable, requiredflatFeefloat-immutable, requiredpercentageFeefloat-immutable, requiredamountfloat-readonlyisVoidedboolean- 

/v2/invoiceLines

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesinvoicebelongs-to-immutable, requiredproductbelongs-toThe product to use for the line.requireddescriptionstringOptional description to display under the product's name on the invoice. quantityfloatThe line's quantity.default: 1unitPricefloatThe price per unit of the product.requiredamountfloat-readonlytaxfloat-readonlytaxRatebelongs-to-readonlydiscountTextstringText to display if the line includes a discount. discountModeenumHow the discount should be calculated. Cash discount: The value of @discountValue@ will be subtracted from the line's amount. Percentage discount: The percentage value of @discountValue@ will be subtracted from the line's amount. discountValuefloatDepending on @discountMode@, either an amount or a percentage value. Percentage value should be supplied as e.g. 25 for 25%. Required if @discountValue@ is set. ignored if @discountValue@ is not set. priorityinteger- 

/v2/invoiceReminderAssociations

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesreminderbelongs-to-requiredinvoicebelongs-to-requiredlateFeebelongs-to-readonly

/v2/invoiceReminders

Supports: get by id, list, create, bulk save, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredcontactbelongs-to-requiredcreatedTimedatetime-readonlyassociationshas-many- flatFeefloat- percentageFeefloat- feeCurrencybelongs-to-requiredsendEmailboolean- contactPersonbelongs-to-requiredemailSubjectstring-requiredemailBodystring-requiredcopyToUserbelongs-to- downloadUrlstring- 

/v2/invoices

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredtypeenumWhether to create an invoice or a credit note. Defaults to @invoice@.immutablecreatedTimedatetime-readonlyapprovedTimedatetime-readonlycontactbelongs-toThe ID of the contact to create the invoice for.immutable, requiredattContactPersonbelongs-toID for a contact person belonging to the contact that should be included as Att: in the invoice address area. entryDatedateThe invoice date. This parameter must not be set if the invoice has already been created.requiredpaymentTermsModeenum-default: unknownpaymentTermsDaysintegerNumber of days (positive or negative) for the mode defined by paymentTermsModerequireddueDatedateThe due date for payment of the invoice.readonlystateenumUsed to change the state of the invoice. Currently the only state change possible is from draft to approved. Once an invoice has been approved, its state can't be changed. Omit from request body if state shouldn't be changed.required, default: "draft"sentStateenumSent state of the email. Invoice is marked as unsent by default, can be marked as printed, sent, opened, viewed.required, default: "unsent"invoiceNostringManually set the invoice number. Invoice numbers has to be unique. If no invoice number is set when the invoice is created, it will automatically be assigned a number using the company's invoice number model. This parameter must not be set if the invoice has already been created.immutable, requiredtaxModeenum- amountfloat-readonlytaxfloat-readonlycurrencybelongs-toThe currency of the invoice. All lines' @unitPrice@ parameters should be in this currency.required, default: unknownexchangeRatefloatThe exchange rate used for invoices in foreign currencies. The value should calculated like this: bq. @exchangeRate@ = @currency@ / @organization's base currency@ If this field is left blank, then today's exchange rate will automatically be used. If @currencyId@ equals the organization's base currency, the value of this field is ignored - it will always be 1. balancefloat-readonlyisPaidboolean-readonlycreditedInvoicebelongs-to-immutablecontactMessagestringOptional message to the contact, to be displayed at the top of the invoice PDF. lineDescriptionstringAutomatically generated based on its lines' descriptions. downloadUrlstring- lineshas-manyLines for the invoice. At minimum, one line must be supplied. If this parameter is set, any existing lines for this invoice will be deleted before adding the new ones. This parameter must not be set if the invoice has already been created.requiredattachmentshas-manyAttachments for the invoice. lateFeeshas-many-readonlybalanceModifiershas-manyPayment associations for the invoice.readonly

/v2/locales

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesnamestring- iconstring- 

/v2/organizations

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesownerUserbelongs-to-requiredcreatedTimedatetimeWhen the organization was createdreadonlynamestring-requiredurlstring-readonlystreetstring- zipcodestring- citystring- countrybelongs-to-immutable, requiredphonestring- faxstring- emailstring- registrationNostring- baseCurrencybelongs-to-immutable, requiredlogoFilebelongs-toOrganization logo. logoPdfFilebelongs-toLogo file to be used with PDFs.readonlylogoUrlstringFull-size logo URLreadonlyiconFilebelongs-toOrganization icon. iconUrlstringFull-size icon URLreadonlyicon48Urlstring48x48 pixels icon URLreadonlyfiscalYearEndMonthinteger-requiredfirstFiscalYearStartdate-requiredfirstFiscalYearEnddate-requiredhasBillVoucherNobooleanWhether or not the company has a bill voucher number subscriptionCardTypestring- subscriptionCardNumberstring- subscriptionCardExpiresdate- subscriptionTransactionbelongs-toThe transaction for the company's recurring subscription. isSubscriptionBankPayerboolean- subscriptionPricefloat- subscriptionPeriodenum-required, default: "monthly"subscriptionDiscountfloat-readonlysubscriptionExpiresdate- isTrialboolean-readonlyisTerminatedboolean- terminationTimedatetimeWhen the company was terminatedreadonlylocalebelongs-toThe organization's default language. Will be used for all contacts unless overridden on a contact level.requiredbillEmailAddressstringAn email can be sent to this address and its attachments will be processed into billsreadonlyisUnmigratedbooleanIf this is true, the company has not yet migrated to our new system.readonlyisLockedbooleanIf this is true, the company is locked.readonlylockedCodeenum-readonlylockedReasonstringReason the company is currently locked.readonlyappUrlstring-readonlyemailAttachmentDeliveryModeenumWhether to deliver attachments by link to customer portal, or with email attachments.requiredhasVatboolean- vatPeriodenum-requireddefaultInvoiceBankAccountbelongs-to- invoiceNoModeenum-requirednextInvoiceNointeger-requiredpaymentTermsModeenum-requiredpaymentTermsDaysinteger-requireddefaultSalesAccountbelongs-to- defaultSalesTaxRulesetbelongs-to- bankSyncStartDatedate- defaultBankFeeAccountbelongs-to- defaultBillBankAccountbelongs-to- 

/v2/postings

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredtransactionbelongs-to-readonlyentryDatedate-readonlytextstring-readonlyaccountbelongs-to-readonlyamountfloat-readonlysideenum-readonlycurrencybelongs-to-readonlysalesTaxReturnbelongs-to-readonlyisVoidedboolean-readonlyisBankMatchedboolean-readonlypriorityinteger-readonly

/v2/productPrices

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesproductbelongs-to-immutable, requiredunitPricefloatCurrency for the unit price.requiredcurrencybelongs-toThe default unit price for invoice lines when the invoice's currency matches this currency.required

/v2/products

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requirednamestringThe name of the product.requireddescriptionstringOptional description that will be used as default on invoice lines with this product. accountbelongs-toThe account that sales of the product should be coded to.required, default: unknownproductNostringA number (or string) that the organization identifies the product by. suppliersProductNostringA number (or string) that the organization's supplier identifies the product by. salesTaxRulesetbelongs-to-default: unknownisArchivedboolean- priceshas-manyThe product can have a unit price for each of the organization's currencies. 

/v2/salesTaxAccounts

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredaccountbelongs-to-requiredtypeenum-requiredpriorityinteger- 

/v2/salesTaxMetaFields

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requirednamestring-requireddescriptionstring- priorityinteger- isPredefinedboolean- 

/v2/salesTaxPayments

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotessalesTaxReturnbelongs-to-immutable, requiredentryDatedate-immutable, requiredaccountbelongs-to-immutable, requiredamountfloat-readonlysideenum-readonlyisVoidedboolean- 

/v2/salesTaxReturns

Supports: get by id, list, update, bulk save, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-readonlycreatedTimedatetime-readonlyperiodTypeenum-readonlyperiodstring-readonlyperiodTextstring- correctionNointeger-readonlystartDatedate-readonlyendDatedate-readonlyreportDeadlinedate- isSettledboolean- isPaidboolean-readonly

/v2/salesTaxRules

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesrulesetbelongs-to-immutable, requiredcountrybelongs-to-immutable, requiredstatebelongs-to-immutablecountryGroupbelongs-to-immutablecontactTypeenum-immutabletaxRatebelongs-to-immutablepriorityinteger-immutable

/v2/salesTaxRulesets

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requirednamestring-immutable, requiredabbreviationstring-immutabledescriptionstring-immutablefallbackTaxRatebelongs-to-immutableisPredefinedboolean-readonlyruleshas-many-immutable

/v2/states

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNotesstateCodestring- namestring- countrybelongs-to- 

/v2/taxRateDeductionComponents

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotestaxRatebelongs-to-immutable, requiredsharefloat-immutable, requiredsourceenum-immutable, requiredaccountbelongs-to-immutable, requiredpriorityinteger- 

/v2/taxRates

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requirednamestring-immutable, requiredabbreviationstring-immutabledescriptionstring-immutableratefloat-immutable, requiredappliesToSalesboolean-immutableappliesToPurchasesboolean-immutableisPredefinedboolean-readonlyisActiveboolean- netAmountMetaFieldbelongs-to-immutabledeductionComponentshas-many-immutable

/v2/transactions

Supports: get by id, list, create, update, bulk save, delete, bulk delete

PropertyTypeDescriptionNotesorganizationbelongs-to-immutable, requiredtransactionNointeger-readonlyvoucherNostring-readonlycreatedTimedatetime-readonlyentryDatedate-readonlyoriginatorbelongs-to-reference-readonlyoriginatorNamestring-readonlyisVoidedboolean-readonlyisVoidboolean-readonlypostingshas-many-readonly

/v2/users

Supports: get by id, list, update, bulk save, bulk delete

PropertyTypeDescriptionNotescreatedTimedatetimeDate/time user was createdreadonlynamestringUser's full name.requiredemailstringUser's email address.requiredphonestringUser's phone number. profilePicFilebelongs-toProfile picture of user.readonlyprofilePicUrlstring-readonlyprofilePic48Urlstring-readonlyisStaffbooleanWhether or not the user is a member of the Billy staff. isSupporterbooleanWhether or not the user is a Billy supporter. isAdminbooleanWhether or not the user is a Billy admin. isSupportAccessAllowedbooleanWhether or not the user chooses to allow supporter access. 

/v2/zipcodes

Supports: get by id, list, create, update, bulk save, bulk delete

PropertyTypeDescriptionNoteszipcodestring- citybelongs-to- statebelongs-to- countrybelongs-to- latitudefloat- longitudefloat-