TallymarkTallymark
Log inGet started for free

Invoices

Invoices start as draft. Sending or taking payment finalizes them (status is no longer draft). Paying in full moves them to paid; a partial payment leaves them open.

Only drafts can be updated or deleted, and an invoice's client can't be changed. Deleted invoices are hidden until you restore them.

View as Markdown

The invoice object

  • Name
    id
    Type
    string
    Description

    Example: 0abcDEF1234567890xyzAB.

  • Name
    number
    Type
    string
  • Name
    status
    Type
    string
    Description

    One of draft, open, paid, void.

  • Name
    client_id
    Type
    string
    Description

    Example: 0abcDEF1234567890xyzAB.

  • Name
    client
    Type
    object
    Description

    The client embedded in invoices and subscriptions, without payment_methods.

  • Name
    client.id
    Type
    string
    Description

    Example: 0abcDEF1234567890xyzAB.

  • Name
    client.name
    Type
    string
  • Name
    client.emails
    Type
    array of string
    Description

    Min 1 items.

  • Name
    client.address
    Type
    string or null
  • Name
    client.currency
    Type
    string
    Description

    Three-letter currency code, in lowercase. Example: usd.

  • Name
    client.language
    Type
    string
    Description

    Two-letter language code, in lowercase. One of da, en, fr, de, it, no, pt, es.

  • Name
    client.default_payment_method_id
    Type
    string or null
    Description

    The card POST /invoices/{id}/pay uses when no payment_method_id is sent. Null when the client has no card on file. Example: 0abcDEF1234567890xyzAB.

  • Name
    client.created_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    client.updated_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    client.is_deleted
    Type
    boolean
  • Name
    currency
    Type
    string
    Description

    Three-letter currency code, in lowercase. Example: usd.

  • Name
    language
    Type
    string
    Description

    Two-letter language code, in lowercase. One of da, en, fr, de, it, no, pt, es.

  • Name
    date
    Type
    date
    Description

    Example: 2024-06-15.

  • Name
    notes
    Type
    string or null
  • Name
    items
    Type
    array of object
  • Name
    items[].description
    Type
    string
  • Name
    items[].amount
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    items[].quantity
    Type
    string
    Description

    Quantity as a decimal string, without trailing zeros. Example: 1.

  • Name
    items[].total
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    discounts
    Type
    array of object
  • Name
    discounts[].amount
    Type
    integer or null
    Description

    Fixed amount off, in cents. Example: 10000. Min 0.

  • Name
    discounts[].percent
    Type
    string or null
    Description

    Percent off the subtotal, as a decimal string without trailing zeros. Example: 12.5.

  • Name
    discount_amount
    Type
    integer
    Description

    Total discount applied to the subtotal, computed from discounts. Example: 10000. Min 0.

  • Name
    taxable_amount
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    tax_rates
    Type
    array of object
  • Name
    tax_rates[].id
    Type
    string
    Description

    The tax rate's ID. Use it in tax_rates. Example: 0abcDEF1234567890xyzAB.

  • Name
    tax_rates[].name
    Type
    string
    Description

    Example: TPS.

  • Name
    tax_rates[].percentage
    Type
    string
    Description

    Percentage as a decimal string, without trailing zeros. Example: 5.

  • Name
    tax_rates[].amount
    Type
    integer
    Description

    Tax amount for this rate. Example: 10000. Min 0.

  • Name
    tax_amount
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    subtotal
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    total
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    amount_paid
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    amount_refunded
    Type
    integer
    Description

    Part of amount_paid that has been refunded. Example: 10000. Min 0.

  • Name
    amount_remaining
    Type
    integer
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    accept_cards
    Type
    boolean
  • Name
    sent_at
    Type
    timestamp or null
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    paid_at
    Type
    timestamp or null
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    created_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    updated_at
    Type
    timestamp
    Description

    Date and time in UTC. Example: 2024-06-15T12:00:00.000000Z.

  • Name
    is_deleted
    Type
    boolean

The invoice object

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
GET/invoices

List invoices

Query parameters

  • Name
    search
    Type
    string
    Description

    Matches number, notes, client name and emails, and item descriptions. Not case-sensitive. Example: design.

  • Name
    status
    Type
    string
    Description

    One of draft, open, paid, void.

  • Name
    client_id
    Type
    string
    Description

    The client ID. Example: 0abcDEF1234567890xyzAB.

  • Name
    limit
    Type
    integer
    Description

    Number of results per page. Default: 10. Min 1. Max 100.

  • Name
    cursor
    Type
    string
    Description

    To get the next page, pass the next_cursor from the previous response.

  • Name
    created_at
    Type
    object
    Description

    Keys gt, gte, lt, lte. Example: created_at[gt]=2024-06-15T12:00:00.000000Z.

  • Name
    updated_at
    Type
    object
    Description

    Keys gt, gte, lt, lte. Example: updated_at[gt]=2024-06-15T12:00:00.000000Z.

Response

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

GET/invoices
curl https://api.tallymark.com/invoices \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "data": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "number": "AB-0001",
      "status": "draft",
      "client_id": "0abcDEF1234567890xyzAB",
      "client": {
        "id": "0abcDEF1234567890xyzAB",
        "name": "Jane Doe",
        "emails": [
          "jane@example.com"
        ],
        "address": "1 Main St",
        "currency": "usd",
        "language": "en",
        "default_payment_method_id": null,
        "created_at": "2024-06-15T12:00:00.000000Z",
        "updated_at": "2024-06-15T12:00:00.000000Z",
        "is_deleted": false
      },
      "currency": "usd",
      "language": "en",
      "date": "2024-06-15",
      "notes": "these are the notes",
      "items": [
        {
          "description": "Design work",
          "amount": 10000,
          "quantity": "1",
          "total": 10000
        }
      ],
      "discounts": [],
      "discount_amount": 0,
      "taxable_amount": 10000,
      "tax_rates": [],
      "tax_amount": 0,
      "subtotal": 10000,
      "total": 10000,
      "amount_paid": 0,
      "amount_refunded": 0,
      "amount_remaining": 10000,
      "accept_cards": false,
      "sent_at": null,
      "paid_at": null,
      "created_at": "2024-06-15T12:00:00.000000Z",
      "updated_at": "2024-06-15T12:00:00.000000Z",
      "is_deleted": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}
POST/invoices

Create an invoice

Creates an invoice. Pass client_id for an existing client, or a client object to create one, but not both.

Without pay or send the invoice is a draft. pay and send are attempts. The invoice is always created and the request succeeds even if they don't go through, so check the returned invoice when it matters:

  • pay: true tries to charge the client's default saved card. If the card is declined, the invoice is returned finalized (open) and unpaid. If the client has no saved card, no charge is attempted. Check status and amount_remaining.
  • send: true tries to email the invoice to the client, after the payment attempt. If the email can't be sent right now, the invoice is returned finalized (open) with sent_at: null. Retry with POST /invoices/{id}/send.

A finalized invoice can no longer be updated or deleted.

Request body

Send exactly one of client_id (an existing client) or client (a new client).

  • Name
    client_id
    Type
    string
    Description

    Example: 0abcDEF1234567890xyzAB.

  • Name
    client
    Type
    object
    Description

    A new client. If a non-deleted client with exactly these emails (same order) already exists, it is reused and updated: its name, its address (cleared when address is omitted), and its currency and language (set to this request's).

  • Name
    client.name
    Type
    string
    Required
    required
    Description

    Max length 255.

  • Name
    client.email
    Type
    string or array of string
    Required
    required
    Description

    One email address, or a list of up to 4. Example: jane@example.com.

  • Name
    client.address
    Type
    string or null
  • Name
    send
    Type
    boolean
    Description

    Try to email the invoice to the client after creating it (and after the payment attempt). Never fails the request. Check sent_at to see if it was sent. Default: false.

  • Name
    pay
    Type
    boolean
    Description

    Try to charge the client's default saved card after creating the invoice. Never fails the request. Check status and amount_remaining to see if it was paid. Default: false.

  • Name
    items
    Type
    array of object
    Required
    required
    Description

    Min 1 items.

  • Name
    items[].description
    Type
    string
    Required
    required
    Description

    Max length 255.

  • Name
    items[].amount
    Type
    integer
    Required
    required
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    items[].quantity
    Type
    number
    Required
    required
    Description

    Rounded to 4 decimals. Example: 1. Min 0.

  • Name
    discounts
    Type
    array of object
    Description

    Max 1 items.

  • Name
    discounts[].amount
    Type
    integer or null
    Description

    Fixed amount off, in cents. Example: 10000. Min 0.

  • Name
    discounts[].percent
    Type
    number or null
    Description

    Percent off the subtotal, up to 4 decimals. Example: 12.5. Min 0. Max 100.

  • Name
    date
    Type
    date
    Required
    required
  • Name
    currency
    Type
    string
    Required
    required
    Description

    Three-letter currency code, in lowercase. Example: usd.

  • Name
    language
    Type
    string
    Required
    required
    Description

    Two-letter language code, in lowercase. One of da, en, fr, de, it, no, pt, es.

  • Name
    tax_rates
    Type
    array of string
    Description

    Tax rate IDs belonging to the account. Deleted tax rates cannot be added, but ones already on the invoice can be kept.

  • Name
    include_default_tax_rates
    Type
    boolean
    Description

    Adds the account's default tax rates on top of tax_rates. On update, if tax_rates is omitted, the defaults are added to the tax rates already on the invoice. A tax rate is never applied twice. Default: false.

  • Name
    accept_cards
    Type
    boolean
    Required
    required
  • Name
    notes
    Type
    string or null

Response

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/invoices
curl -X POST https://api.tallymark.com/invoices \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "address": "1 Main St"
  },
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": 1
    }
  ],
  "date": "2024-06-15",
  "currency": "usd",
  "language": "en",
  "accept_cards": false,
  "notes": "these are the notes"
}'

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
GET/invoices/{id}

Show an invoice

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The invoice ID. Example: 0abcDEF1234567890xyzAB.

Response

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

GET/invoices/{id}
curl https://api.tallymark.com/invoices/0abcDEF1234567890xyzAB \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
POST/invoices/{id}/update

Update an invoice

Updates a draft invoice. Only the fields you send are changed; omitted fields keep their current value. Send notes: null to clear the notes, and discounts: [] or tax_rates: [] to remove them. The client can't be changed.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The invoice ID. Example: 0abcDEF1234567890xyzAB.

Request body

Send at most one discount.

  • Name
    items
    Type
    array of object
    Description

    Min 1 items.

  • Name
    items[].description
    Type
    string
    Required
    required
    Description

    Max length 255.

  • Name
    items[].amount
    Type
    integer
    Required
    required
    Description

    Amount in the smallest currency unit (cents). Example: 10000. Min 0.

  • Name
    items[].quantity
    Type
    number
    Required
    required
    Description

    Rounded to 4 decimals. Example: 1. Min 0.

  • Name
    discounts
    Type
    array of object
    Description

    Max 1 items.

  • Name
    discounts[].amount
    Type
    integer or null
    Description

    Fixed amount off, in cents. Example: 10000. Min 0.

  • Name
    discounts[].percent
    Type
    number or null
    Description

    Percent off the subtotal, up to 4 decimals. Example: 12.5. Min 0. Max 100.

  • Name
    date
    Type
    date
  • Name
    currency
    Type
    string
    Description

    Three-letter currency code, in lowercase. Example: usd.

  • Name
    language
    Type
    string
    Description

    Two-letter language code, in lowercase. One of da, en, fr, de, it, no, pt, es.

  • Name
    tax_rates
    Type
    array of string
    Description

    Tax rate IDs belonging to the account. Deleted tax rates cannot be added, but ones already on the invoice can be kept.

  • Name
    include_default_tax_rates
    Type
    boolean
    Description

    Adds the account's default tax rates on top of tax_rates. On update, if tax_rates is omitted, the defaults are added to the tax rates already on the invoice. A tax rate is never applied twice. Default: false.

  • Name
    accept_cards
    Type
    boolean
  • Name
    notes
    Type
    string or null

Response

Errors

  • Name
    400
    Type
    invoice_finalized
    Description

    This invoice is finalized and cannot be updated. Only drafts can be updated.

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/invoices/{id}/update
curl -X POST https://api.tallymark.com/invoices/0abcDEF1234567890xyzAB/update \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "description": "Design work",
      "amount": 15000,
      "quantity": 2
    }
  ],
  "notes": "Thanks for your business."
}'

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
POST/invoices/{id}/send

Send an invoice

Finalizes a draft (status becomes open) and emails the client. Sending an already-sent invoice emails it again; sent_at keeps the time of the first send. Sending a paid invoice emails the client a receipt.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The invoice ID. Example: 0abcDEF1234567890xyzAB.

Response

Errors

  • Name
    400
    Type
    invoice_void
    Description

    This invoice is void and cannot be sent.

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    403
    Type
    account_not_verified
    Description

    Verify your account's email before performing this action.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    429
    Description

    Too many requests, or the account can't send email right now because it hit its email limit.

  • Name
    429
    Type
    too_many_emails
    Description

    Unable to send invoice at this time.

Request

POST/invoices/{id}/send
curl -X POST https://api.tallymark.com/invoices/0abcDEF1234567890xyzAB/send \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
POST/invoices/{id}/delete

Delete a draft invoice

Deletes a draft invoice. You can restore it later. Only drafts can be deleted: once an invoice is sent or paid, it's final.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The invoice ID. Example: 0abcDEF1234567890xyzAB.

Response

  • Name
    200
    Description

    Deleted invoice (is_deleted true). Returns a invoice object.

Errors

  • Name
    400
    Type
    invoice_finalized
    Description

    This invoice is finalized and cannot be deleted. Only drafts can be deleted.

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/invoices/{id}/delete
curl -X POST https://api.tallymark.com/invoices/0abcDEF1234567890xyzAB/delete \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
POST/invoices/{id}/restore

Restore a deleted invoice

Restores a deleted draft invoice.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The invoice ID. Example: 0abcDEF1234567890xyzAB.

Response

  • Name
    200
    Description

    Restored invoice (is_deleted false). Returns a invoice object.

Errors

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/invoices/{id}/restore
curl -X POST https://api.tallymark.com/invoices/0abcDEF1234567890xyzAB/restore \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
POST/invoices/{id}/pay

Pay an invoice

Pays amount cents, or the full amount_remaining when amount is omitted. A draft is finalized first. The invoice becomes paid once nothing is left to pay; after a partial payment it stays open with a lower amount_remaining.

  • processor: cash records a payment made outside Tallymark (cash, check, bank transfer). No money moves.
  • processor: stripe charges a card the client saved when paying in the app: payment_method_id from the client's payment_methods, or the client's default_payment_method_id when omitted.

If the card is declined, the invoice stays unpaid and you can call this endpoint again to retry.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The invoice ID. Example: 0abcDEF1234567890xyzAB.

Request body

  • Name
    processor
    Type
    string
    Required
    required
    Description

    cash is recorded outside Tallymark (cash, check, bank transfer). No money moves. One of stripe, cash.

  • Name
    payment_method_id
    Type
    string or null
    Description

    stripe only. One of the client's payment_methods. Omit to use the client's default card. Example: 0abcDEF1234567890xyzAB.

  • Name
    amount
    Type
    integer or null
    Description

    Omit (or null) to pay the full amount_remaining. Can't be more than amount_remaining. Example: 10000. Min 1.

Response

Errors

  • Name
    400
    Type
    invoice_void
    Description

    This invoice is void and cannot be paid.

  • Name
    400
    Type
    amount_too_large
    Description

    The amount is more than what is left to pay on this invoice.

  • Name
    400
    Type
    amount_too_small
    Description

    The amount is below the minimum card charge for this currency.

  • Name
    400
    Type
    payment_method_not_found
    Description

    The payment method was not found on this client.

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    402
    Type
    payment_failed
    Description

    The payment could not be processed.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    403
    Type
    account_not_verified
    Description

    Verify your account's email before performing this action.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    409
    Type
    already_paid
    Description

    This invoice is already paid.

  • Name
    409
    Type
    stripe_not_connected
    Description

    This account has not connected Stripe.

  • Name
    409
    Type
    no_payment_method
    Description

    This client has no card on file.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/invoices/{id}/pay
curl -X POST https://api.tallymark.com/invoices/0abcDEF1234567890xyzAB/pay \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "processor": "stripe",
  "payment_method_id": "0abcDEF1234567890xyzAB",
  "amount": 2500
}'

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}
POST/invoices/{id}/refund

Refund an invoice

Refunds amount cents, or everything still refundable (amount_paid − amount_refunded) when amount is omitted. Card payments are refunded to the card. Refunding doesn't change status or amount_remaining; check amount_refunded. The client is emailed when the account notifies clients.

Path parameters

  • Name
    id
    Type
    string
    Required
    required
    Description

    The invoice ID. Example: 0abcDEF1234567890xyzAB.

Request body

  • Name
    amount
    Type
    integer or null
    Description

    Omit (or null) to refund everything still refundable. Example: 10000. Min 1.

Response

Errors

  • Name
    400
    Type
    amount_too_large
    Description

    The amount is more than what is left to refund on this invoice.

  • Name
    400
    Type
    request_failed
    Description

    Your request could not be processed.

  • Name
    400
    Type
    api_version_unsupported
    Description

    The requested API version is not supported. Current version: 2026-08-21

  • Name
    401
    Type
    api_key_missing
    Description

    The API key is missing.

  • Name
    401
    Type
    api_key_invalid
    Description

    The API key is invalid or has been revoked.

  • Name
    402
    Type
    refund_failed
    Description

    The invoice could not be refunded.

  • Name
    403
    Type
    api_key_read_only
    Description

    This API key is read-only and cannot make write requests.

  • Name
    404
    Description

    The record doesn't exist or was deleted.

  • Name
    409
    Type
    nothing_to_refund
    Description

    This invoice has no payments left to refund.

  • Name
    409
    Type
    stripe_not_connected
    Description

    This account has not connected Stripe.

  • Name
    422
    Description

    The request body or query parameters are invalid.

  • Name
    429
    Description

    Too many requests. The limit is 300 requests per 5 minutes.

Request

POST/invoices/{id}/refund
curl -X POST https://api.tallymark.com/invoices/0abcDEF1234567890xyzAB/refund \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 2500
}'

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "number": "AB-0001",
  "status": "draft",
  "client_id": "0abcDEF1234567890xyzAB",
  "client": {
    "id": "0abcDEF1234567890xyzAB",
    "name": "Jane Doe",
    "emails": [
      "jane@example.com"
    ],
    "address": "1 Main St",
    "currency": "usd",
    "language": "en",
    "default_payment_method_id": null,
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "date": "2024-06-15",
  "notes": "these are the notes",
  "items": [
    {
      "description": "Design work",
      "amount": 10000,
      "quantity": "1",
      "total": 10000
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "amount_paid": 0,
  "amount_refunded": 0,
  "amount_remaining": 10000,
  "accept_cards": false,
  "sent_at": null,
  "paid_at": null,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}