Skip to main content
API Reference
Cards
Checkbooks

Checkbooks are sets of blank checks that Increase prints and mails on your behalf.

Events
Your application can listen to webhooks about this resource. The events about Checkbooks will have the categories "checkbook.created" or "checkbook.updated".
The Checkbook object
{
  "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
  "created_at": "2020-01-31T23:59:59Z",
  "id": "checkbook_7iudxhxum6vlkcjxmi8y",
  "idempotency_key": null,
  "mailing_address": {
    "city": "New York",
    "line1": "33 Liberty Street",
    "line2": null,
    "name": "Ian Crease",
    "postal_code": "10045",
    "state": "NY"
  },
  "payer": [
    {
      "contents": "National Phonograph Company"
    },
    {
      "contents": "33 Liberty Street"
    },
    {
      "contents": "New York, NY 10045"
    }
  ],
  "return_address": {
    "city": "San Francisco",
    "line1": "244 Kearny St",
    "line2": "Floor 8",
    "name": "Undeliverable Mail",
    "postal_code": "94108",
    "state": "CA"
  },
  "status": "mailed",
  "style": "three_ring_binder",
  "tracking_updates": [
    {
      "category": "in_transit",
      "country": "US",
      "created_at": "2020-01-31T23:59:59Z",
      "postal_code": "10045"
    },
    {
      "category": "delivered",
      "country": "US",
      "created_at": "2020-01-31T23:59:59Z",
      "postal_code": "10045"
    }
  ],
  "type": "checkbook"
}
Attributes
account_number_id
string

The identifier of the Account Number the Checkbook is attached to.

More about Account Numbers.
created_at
string

The ISO 8601 date and time at which the Checkbook was created.

id
string

The Checkbook’s identifier.

idempotency_key
string
Nullable

The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about idempotency.

mailing_address
dictionary

The destination address that the Checkbook will be mailed to.

payer
array

The payer information printed on the top-left corner of each check.

return_address
dictionary

The address the Checkbook will return to if there is a delivery issue.

status
enum

The lifecycle status of the Checkbook.

style
enum

The physical format of the Checkbook.

tracking_updates
array

Tracking updates relating to the Checkbook’s delivery.

type
string

A constant representing the object’s type. For this resource it will always be checkbook.

List Checkbooks
curl \
  --url "${INCREASE_URL}/checkbooks" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
import Increase from 'increase';

const client = new Increase({
  apiKey: process.env['INCREASE_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const checkbook of client.checkbooks.list()) {
  console.log(checkbook.id);
}
import os
from increase import Increase

client = Increase(
    api_key=os.environ.get("INCREASE_API_KEY"),  # This is the default and can be omitted
)
page = client.checkbooks.list()
page = page.data[0]
print(page.id)
require "increase"

increase = Increase::Client.new(
  api_key: ENV["INCREASE_API_KEY"] # This is the default and can be omitted
)

page = increase.checkbooks.list

puts(page)
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/Increase/increase-go"
	"github.com/Increase/increase-go/option"
)

func main() {
	client := increase.NewClient(
		option.WithAPIKey(os.Getenv("INCREASE_API_KEY")), // This is the default and can be omitted
	)
	page, err := client.Checkbooks.List(context.TODO(), increase.CheckbookListParams{})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", page)
}
package com.increase.api.example;

import com.increase.api.client.IncreaseClient;
import com.increase.api.client.okhttp.IncreaseOkHttpClient;
import com.increase.api.models.checkbooks.CheckbookListPage;
import com.increase.api.models.checkbooks.CheckbookListParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        IncreaseClient client = IncreaseOkHttpClient.fromEnv();

        CheckbookListPage page = client.checkbooks().list();
    }
}
package com.increase.api.example

import com.increase.api.client.IncreaseClient
import com.increase.api.client.okhttp.IncreaseOkHttpClient
import com.increase.api.models.checkbooks.CheckbookListPage
import com.increase.api.models.checkbooks.CheckbookListParams

fun main() {
    val client: IncreaseClient = IncreaseOkHttpClient.fromEnv()

    val page: CheckbookListPage = client.checkbooks().list()
}
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Increase\Client;
use Increase\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('INCREASE_API_KEY'));

try {
  $page = $client->checkbooks->list(
    accountNumberID: 'account_number_id',
    cursor: 'cursor',
    idempotencyKey: 'x',
    limit: 1,
    status: ['in' => ['pending_submission']],
  );

  var_dump($page);
} catch (APIException $e) {
  echo $e->getMessage();
}
using System;
using Increase.Api;
using Increase.Api.Models.Checkbooks;

IncreaseClient client = new();

CheckbookListParams parameters = new();

var page = await client.Checkbooks.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}
Returns a list response:
{
  "data": [
    { /* Checkbook object */ },
    { /* Checkbook object */ }
    /* ... */
  ],
  "next_cursor": "v57w5d",
}
Parameters
account_number_id
string

Filter Checkbooks to those attached to the specified Account Number.

More about Account Numbers.
status.in
array of strings

Filter Checkbooks for those with the specified status or statuses. For GET requests, this should be encoded as a comma-delimited string, such as ?in=one,two,three.

idempotency_key
string

Filter records to the one with the specified idempotency_key you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about idempotency.

Between 1 and 200 characters
More parameters
Create a Checkbook
curl -X "POST" \
  --url "${INCREASE_URL}/checkbooks" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "account_number_id": "account_number_v18nkfqm6afpsrvy82b2",
    "mailing_address": {
      "city": "New York",
      "line1": "33 Liberty Street",
      "name": "Ian Crease",
      "postal_code": "10045",
      "state": "NY"
    },
    "payer": [
      {
        "contents": "National Phonograph Company"
      },
      {
        "contents": "33 Liberty Street"
      },
      {
        "contents": "New York, NY 10045"
      }
    ]
  }'
import Increase from 'increase';

const client = new Increase({
  apiKey: process.env['INCREASE_API_KEY'], // This is the default and can be omitted
});

const checkbook = await client.checkbooks.create({
  account_number_id: 'account_number_v18nkfqm6afpsrvy82b2',
  mailing_address: {
    city: 'New York',
    line1: '33 Liberty Street',
    name: 'Ian Crease',
    postal_code: '10045',
    state: 'NY',
  },
  payer: [
    { contents: 'National Phonograph Company' },
    { contents: '33 Liberty Street' },
    { contents: 'New York, NY 10045' },
  ],
});

console.log(checkbook.id);
import os
from increase import Increase

client = Increase(
    api_key=os.environ.get("INCREASE_API_KEY"),  # This is the default and can be omitted
)
checkbook = client.checkbooks.create(
    account_number_id="account_number_v18nkfqm6afpsrvy82b2",
    mailing_address={
        "city": "New York",
        "line1": "33 Liberty Street",
        "name": "Ian Crease",
        "postal_code": "10045",
        "state": "NY",
    },
    payer=[{
        "contents": "National Phonograph Company"
    }, {
        "contents": "33 Liberty Street"
    }, {
        "contents": "New York, NY 10045"
    }],
)
print(checkbook.id)
require "increase"

increase = Increase::Client.new(
  api_key: ENV["INCREASE_API_KEY"] # This is the default and can be omitted
)

checkbook = increase.checkbooks.create(
  account_number_id: "account_number_v18nkfqm6afpsrvy82b2",
  mailing_address: {city: "New York", line1: "33 Liberty Street", name: "Ian Crease", postal_code: "10045", state: "NY"},
  payer: [{contents: "National Phonograph Company"}, {contents: "33 Liberty Street"}, {contents: "New York, NY 10045"}]
)

puts(checkbook)
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/Increase/increase-go"
	"github.com/Increase/increase-go/option"
)

func main() {
	client := increase.NewClient(
		option.WithAPIKey(os.Getenv("INCREASE_API_KEY")), // This is the default and can be omitted
	)
	checkbook, err := client.Checkbooks.New(context.TODO(), increase.CheckbookNewParams{
		AccountNumberID: increase.F("account_number_v18nkfqm6afpsrvy82b2"),
		MailingAddress: increase.F(increase.CheckbookNewParamsMailingAddress{
			City:       increase.F("New York"),
			Line1:      increase.F("33 Liberty Street"),
			Name:       increase.F("Ian Crease"),
			PostalCode: increase.F("10045"),
			State:      increase.F("NY"),
		}),
		Payer: increase.F([]increase.CheckbookNewParamsPayer{{
			Contents: increase.F("National Phonograph Company"),
		}, {
			Contents: increase.F("33 Liberty Street"),
		}, {
			Contents: increase.F("New York, NY 10045"),
		}}),
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", checkbook.ID)
}
package com.increase.api.example;

import com.increase.api.client.IncreaseClient;
import com.increase.api.client.okhttp.IncreaseOkHttpClient;
import com.increase.api.models.checkbooks.Checkbook;
import com.increase.api.models.checkbooks.CheckbookCreateParams;
import java.util.List;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        IncreaseClient client = IncreaseOkHttpClient.fromEnv();

        CheckbookCreateParams params = CheckbookCreateParams.builder()
            .accountNumberId("account_number_v18nkfqm6afpsrvy82b2")
            .mailingAddress(CheckbookCreateParams.MailingAddress.builder()
                .city("New York")
                .line1("33 Liberty Street")
                .name("Ian Crease")
                .postalCode("10045")
                .state("NY")
                .build())
            .payer(List.of(
              CheckbookCreateParams.Payer.builder()
                  .contents("National Phonograph Company")
                  .build(),
              CheckbookCreateParams.Payer.builder()
                  .contents("33 Liberty Street")
                  .build(),
              CheckbookCreateParams.Payer.builder()
                  .contents("New York, NY 10045")
                  .build()
            ))
            .build();
        Checkbook checkbook = client.checkbooks().create(params);
    }
}
package com.increase.api.example

import com.increase.api.client.IncreaseClient
import com.increase.api.client.okhttp.IncreaseOkHttpClient
import com.increase.api.models.checkbooks.Checkbook
import com.increase.api.models.checkbooks.CheckbookCreateParams

fun main() {
    val client: IncreaseClient = IncreaseOkHttpClient.fromEnv()

    val params: CheckbookCreateParams = CheckbookCreateParams.builder()
        .accountNumberId("account_number_v18nkfqm6afpsrvy82b2")
        .mailingAddress(CheckbookCreateParams.MailingAddress.builder()
            .city("New York")
            .line1("33 Liberty Street")
            .name("Ian Crease")
            .postalCode("10045")
            .state("NY")
            .build())
        .payer(listOf(
          CheckbookCreateParams.Payer.builder()
              .contents("National Phonograph Company")
              .build(),
          CheckbookCreateParams.Payer.builder()
              .contents("33 Liberty Street")
              .build(),
          CheckbookCreateParams.Payer.builder()
              .contents("New York, NY 10045")
              .build(),
        ))
        .build()
    val checkbook: Checkbook = client.checkbooks().create(params)
}
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Increase\Client;
use Increase\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('INCREASE_API_KEY'));

try {
  $checkbook = $client->checkbooks->create(
    accountNumberID: 'account_number_v18nkfqm6afpsrvy82b2',
    mailingAddress: [
      'city' => 'New York',
      'line1' => '33 Liberty Street',
      'name' => 'Ian Crease',
      'postalCode' => '10045',
      'state' => 'NY',
      'line2' => 'line2',
    ],
    payer: [
      ['contents' => 'National Phonograph Company'],
      ['contents' => '33 Liberty Street'],
      ['contents' => 'New York, NY 10045'],
    ],
  );

  var_dump($checkbook);
} catch (APIException $e) {
  echo $e->getMessage();
}
using System;
using Increase.Api;
using Increase.Api.Models.Checkbooks;

IncreaseClient client = new();

CheckbookCreateParams parameters = new()
{
    AccountNumberID = "account_number_v18nkfqm6afpsrvy82b2",
    MailingAddress = new()
    {
        City = "New York",
        Line1 = "33 Liberty Street",
        Name = "Ian Crease",
        PostalCode = "10045",
        State = "NY",
        Line2 = "line2",
    },
    Payer =
    [
        new("National Phonograph Company"),
        new("33 Liberty Street"),
        new("New York, NY 10045"),
    ],
};

var checkbook = await client.Checkbooks.Create(parameters);

Console.WriteLine(checkbook);
Parameters
account_number_id
string
Required

The identifier of the Account Number that the checks will draw from. The Account Number must be active.

More about Account Numbers.
mailing_address
dictionary
Required

The destination address that the Checkbook will be mailed to.

payer
array
Required

The payer of the checks. This will be printed on the top-left corner of each check. This should be an array of up to 4 elements, each of which represents a line of the payer.

Retrieve a Checkbook
curl \
  --url "${INCREASE_URL}/checkbooks/checkbook_7iudxhxum6vlkcjxmi8y" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
import Increase from 'increase';

const client = new Increase({
  apiKey: process.env['INCREASE_API_KEY'], // This is the default and can be omitted
});

const checkbook = await client.checkbooks.retrieve('checkbook_7iudxhxum6vlkcjxmi8y');

console.log(checkbook.id);
import os
from increase import Increase

client = Increase(
    api_key=os.environ.get("INCREASE_API_KEY"),  # This is the default and can be omitted
)
checkbook = client.checkbooks.retrieve(
    "checkbook_7iudxhxum6vlkcjxmi8y",
)
print(checkbook.id)
require "increase"

increase = Increase::Client.new(
  api_key: ENV["INCREASE_API_KEY"] # This is the default and can be omitted
)

checkbook = increase.checkbooks.retrieve("checkbook_7iudxhxum6vlkcjxmi8y")

puts(checkbook)
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/Increase/increase-go"
	"github.com/Increase/increase-go/option"
)

func main() {
	client := increase.NewClient(
		option.WithAPIKey(os.Getenv("INCREASE_API_KEY")), // This is the default and can be omitted
	)
	checkbook, err := client.Checkbooks.Get(context.TODO(), "checkbook_7iudxhxum6vlkcjxmi8y")
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", checkbook.ID)
}
package com.increase.api.example;

import com.increase.api.client.IncreaseClient;
import com.increase.api.client.okhttp.IncreaseOkHttpClient;
import com.increase.api.models.checkbooks.Checkbook;
import com.increase.api.models.checkbooks.CheckbookRetrieveParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        IncreaseClient client = IncreaseOkHttpClient.fromEnv();

        Checkbook checkbook = client.checkbooks().retrieve("checkbook_7iudxhxum6vlkcjxmi8y");
    }
}
package com.increase.api.example

import com.increase.api.client.IncreaseClient
import com.increase.api.client.okhttp.IncreaseOkHttpClient
import com.increase.api.models.checkbooks.Checkbook
import com.increase.api.models.checkbooks.CheckbookRetrieveParams

fun main() {
    val client: IncreaseClient = IncreaseOkHttpClient.fromEnv()

    val checkbook: Checkbook = client.checkbooks().retrieve("checkbook_7iudxhxum6vlkcjxmi8y")
}
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Increase\Client;
use Increase\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('INCREASE_API_KEY'));

try {
  $checkbook = $client->checkbooks->retrieve('checkbook_7iudxhxum6vlkcjxmi8y');

  var_dump($checkbook);
} catch (APIException $e) {
  echo $e->getMessage();
}
using System;
using Increase.Api;
using Increase.Api.Models.Checkbooks;

IncreaseClient client = new();

CheckbookRetrieveParams parameters = new()
{
    CheckbookID = "checkbook_7iudxhxum6vlkcjxmi8y"
};

var checkbook = await client.Checkbooks.Retrieve(parameters);

Console.WriteLine(checkbook);
Parameters
checkbook_id
string
Required

The identifier of the Checkbook.

More about Checkbooks.
Stop a Checkbook

Stop a Checkbook. Stopping a Checkbook stops all of its checks that have not yet been deposited.

curl -X "POST" \
  --url "${INCREASE_URL}/checkbooks/checkbook_7iudxhxum6vlkcjxmi8y/stop" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
import Increase from 'increase';

const client = new Increase({
  apiKey: process.env['INCREASE_API_KEY'], // This is the default and can be omitted
});

const checkbook = await client.checkbooks.stop('checkbook_7iudxhxum6vlkcjxmi8y');

console.log(checkbook.id);
import os
from increase import Increase

client = Increase(
    api_key=os.environ.get("INCREASE_API_KEY"),  # This is the default and can be omitted
)
checkbook = client.checkbooks.stop(
    "checkbook_7iudxhxum6vlkcjxmi8y",
)
print(checkbook.id)
require "increase"

increase = Increase::Client.new(
  api_key: ENV["INCREASE_API_KEY"] # This is the default and can be omitted
)

checkbook = increase.checkbooks.stop("checkbook_7iudxhxum6vlkcjxmi8y")

puts(checkbook)
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/Increase/increase-go"
	"github.com/Increase/increase-go/option"
)

func main() {
	client := increase.NewClient(
		option.WithAPIKey(os.Getenv("INCREASE_API_KEY")), // This is the default and can be omitted
	)
	checkbook, err := client.Checkbooks.Stop(context.TODO(), "checkbook_7iudxhxum6vlkcjxmi8y")
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", checkbook.ID)
}
package com.increase.api.example;

import com.increase.api.client.IncreaseClient;
import com.increase.api.client.okhttp.IncreaseOkHttpClient;
import com.increase.api.models.checkbooks.Checkbook;
import com.increase.api.models.checkbooks.CheckbookStopParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        IncreaseClient client = IncreaseOkHttpClient.fromEnv();

        Checkbook checkbook = client.checkbooks().stop("checkbook_7iudxhxum6vlkcjxmi8y");
    }
}
package com.increase.api.example

import com.increase.api.client.IncreaseClient
import com.increase.api.client.okhttp.IncreaseOkHttpClient
import com.increase.api.models.checkbooks.Checkbook
import com.increase.api.models.checkbooks.CheckbookStopParams

fun main() {
    val client: IncreaseClient = IncreaseOkHttpClient.fromEnv()

    val checkbook: Checkbook = client.checkbooks().stop("checkbook_7iudxhxum6vlkcjxmi8y")
}
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Increase\Client;
use Increase\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('INCREASE_API_KEY'));

try {
  $checkbook = $client->checkbooks->stop('checkbook_7iudxhxum6vlkcjxmi8y');

  var_dump($checkbook);
} catch (APIException $e) {
  echo $e->getMessage();
}
using System;
using Increase.Api;
using Increase.Api.Models.Checkbooks;

IncreaseClient client = new();

CheckbookStopParams parameters = new()
{
    CheckbookID = "checkbook_7iudxhxum6vlkcjxmi8y"
};

var checkbook = await client.Checkbooks.Stop(parameters);

Console.WriteLine(checkbook);
Parameters
checkbook_id
string
Required

The identifier of the Checkbook to stop.

More about Checkbooks.
Sandbox: Mail a Checkbook

Simulates the mailing of a Checkbook, which happens periodically throughout the day in production but can be sped up in sandbox. This Checkbook must have a status of pending_submission or pending_mailing.

curl -X "POST" \
  --url "${INCREASE_URL}/simulations/checkbooks/checkbook_7iudxhxum6vlkcjxmi8y/mail" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
import Increase from 'increase';

const client = new Increase({
  apiKey: process.env['INCREASE_API_KEY'], // This is the default and can be omitted
});

const checkbook = await client.simulations.checkbooks.mail('checkbook_7iudxhxum6vlkcjxmi8y');

console.log(checkbook.id);
import os
from increase import Increase

client = Increase(
    api_key=os.environ.get("INCREASE_API_KEY"),  # This is the default and can be omitted
)
checkbook = client.simulations.checkbooks.mail(
    "checkbook_7iudxhxum6vlkcjxmi8y",
)
print(checkbook.id)
require "increase"

increase = Increase::Client.new(
  api_key: ENV["INCREASE_API_KEY"] # This is the default and can be omitted
)

checkbook = increase.simulations.checkbooks.mail("checkbook_7iudxhxum6vlkcjxmi8y")

puts(checkbook)
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/Increase/increase-go"
	"github.com/Increase/increase-go/option"
)

func main() {
	client := increase.NewClient(
		option.WithAPIKey(os.Getenv("INCREASE_API_KEY")), // This is the default and can be omitted
	)
	checkbook, err := client.Simulations.Checkbooks.Mail(context.TODO(), "checkbook_7iudxhxum6vlkcjxmi8y")
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", checkbook.ID)
}
package com.increase.api.example;

import com.increase.api.client.IncreaseClient;
import com.increase.api.client.okhttp.IncreaseOkHttpClient;
import com.increase.api.models.checkbooks.Checkbook;
import com.increase.api.models.simulations.checkbooks.CheckbookMailParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        IncreaseClient client = IncreaseOkHttpClient.fromEnv();

        Checkbook checkbook = client.simulations().checkbooks().mail("checkbook_7iudxhxum6vlkcjxmi8y");
    }
}
package com.increase.api.example

import com.increase.api.client.IncreaseClient
import com.increase.api.client.okhttp.IncreaseOkHttpClient
import com.increase.api.models.checkbooks.Checkbook
import com.increase.api.models.simulations.checkbooks.CheckbookMailParams

fun main() {
    val client: IncreaseClient = IncreaseOkHttpClient.fromEnv()

    val checkbook: Checkbook = client.simulations().checkbooks().mail("checkbook_7iudxhxum6vlkcjxmi8y")
}
<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Increase\Client;
use Increase\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('INCREASE_API_KEY'));

try {
  $checkbook = $client->simulations->checkbooks->mail(
    'checkbook_7iudxhxum6vlkcjxmi8y'
  );

  var_dump($checkbook);
} catch (APIException $e) {
  echo $e->getMessage();
}
using System;
using Increase.Api;
using Increase.Api.Models.Simulations.Checkbooks;

IncreaseClient client = new();

CheckbookMailParams parameters = new()
{
    CheckbookID = "checkbook_7iudxhxum6vlkcjxmi8y"
};

var checkbook = await client.Simulations.Checkbooks.Mail(parameters);

Console.WriteLine(checkbook);
Parameters
checkbook_id
string
Required

The identifier of the Checkbook you wish to mail.

More about Checkbooks.