What you can do with the QuickBooks Payments API

The QuickBooks Payments API uses the REST framework. It uses standard HTTP methods and JSON for input and output.

Generally, our APIs let apps process payments, refund charges, and manage credit cards and bank accounts.

In this guide, we’ll cover how our API works and what resources, operations, and features we support.

Tip: This guide only covers QuickBooks Payments and its APIs.

See the QuickBooks Online API
See the QuickBooks Desktop API
See the QuickBooks Time API (formally T-Sheets)

Choosing API entities to build your app

When you start building your app, decide generally what you want it to do. Then, pick the specific API entities needed to use the relevant features and data. Visit the QuickBooks Payments API Explorer to learn more about specific entities.

If you don’t want to start from scratch, you can build your app around one of workflow examples. You can use these guides as a basic foundation for your app and expand on it.

Basic Payments API resources and concepts

By “resources,” we mean the API entities your app can use to create or update data in QuickBooks Online. Here are key customer-facing concepts and the corresponding API:

Charges: Allows your app to send and receive payments, and process refunds, using credit cards.

Relevant API entities: Charges

Tokens: An opaque container that holds a cardholder’s credit card or bank account info.

Relevant API entities: Tokens

Bank accounts: Allows your app to process payments using bank accounts.

Relevant API entities: BankAccounts

Cards: Allows your app to store and manage credit card info for future payments.

Relevant API entities: Cards

EChecks: Allows your app to process payments using electronic checks.

Relevant API entities: EChecks

Basic API operations

Visit the QuickBooks Payments API Explorer to see the operations each entity supports. Besides standard CRUD operations, our API has a few unique operations:

Update operations

There are two ways to update entities:

Use sparse updates to change specific subsets of fields
Use full updates to make broad changes

Keep in mind, you must serially perform updates and additions to list entities (customers, accounts, vendors, classes etc).

Use sparse updates instead of full updates

There are several advantages to sparse updates.

Prevent unintended overwrites: Apps don’t always use every field for an entity. If it does a full update and intends to only update used fields, it will unintentionally clear fields that weren’t sent. If you need to only update used fields, consider sparse updates.
Reduce request payload sizes: Sparse updates generally reduce payload sizes. This is especially useful for mobile apps since lower speeds and spotty connections can already impact performance. Also, many mobile users are sensitive to high data usage.
Facilitate future field additions: You can use sparse updates to add new fields to an entity. This acts as a “merge” for an existing entity. It lets you make changes without inadvertently clearing existing fields, which is especially important for past versions of production apps.

Making sparse updates

Sparse update operations let you update specific fields of an existing entity.

Specify the writable properties you want to update in the request body. Nothing else gets updated. Missing attributes also aren’t updated or cleared (in contrast to a full update).

In the request body, you must include the sparse="true" attribute.

Using sparse updates to clear fields

Making full updates

Full update operations update all writable attributes of an existing entity.

If a writable attribute is omitted or missing from the request body, full updates clear the field’s value and set it to NULL.

In the request body, use the id field to specify the entity you want to update.

Tip: Read-only values are ignored and replaced by defaults. No error is returned. We note read-only attributes for individual entities in the API Explorer.

Delete operations

There are two ways to delete entities:

Use soft deletes for list entities (customers, accounts, vendors, etc). This deactivates the entity. You can reactivate it later on.
Use hard deletes for transaction entities (invoices, estimates, purchase orders, sales receipts, etc). This permanently deletes the entity. You can’t undo hard deletes.

Certain API entities only allow certain delete operations. We note the supported delete operations for individual entities in the API Explorer.

Soft deletes

end-userReferences to inactive entities remain intact.

You can only soft delete list (customers, vendors, accounts, etc.) entities.

When you create a new object, it starts in an “active” state. To do a soft delete, use one of the update operations. Set the value of the active field to false in the request. This makes the entity inactive.

To make it active again, do another update and set the value back to true.

Note: If you query and don’t filter for “inactive” entities, the server only returns results for “active” entities.

Hard delete

Hard deletes permanently change data. It deletes the entire entity. Once you do a hard delete, you can’t undo it.

You can only hard delete transaction (invoices, estimates, purchase orders, sales receipts, etc) entities.

There are two ways to structure hard delete requests:

For Bill, BillPayment, CreditMemo, Estimate, Invoice, JournalEntry, Payment, Purchase, PurchaseOrder, RefundReceipt, SalesReceipt, TimeActivity, and VendorCredit entities: You can do a “simplified delete.” Enter the id and syncToken in the request body.
For all other transaction entities: Include the full payload for the entity as returned in a read response in the request body.

Review QuickBooks-specific payments use cases

As you develop your app, you’ll encounter many accounting concepts. Even if you have an accounting background, there are some workflows and concepts that are unique to QuickBooks Online.

We recommend you check out our overview of basic accounting and QuickBooks-specific accounting use cases.