Subscriptions

A subscription generates a regular invoice every interval, starting on start_date. Generated invoices are normal invoices and appear in GET /invoices.

Statuses: draft (never generates invoices), active, paused. Status can't be set through update. Use /activate and /pause instead. A subscription with number_of_invoices set is paused automatically once invoices_generated reaches it.

Invoices are generated when next_invoice_at is today or earlier. If several billing periods are already due (e.g. a past start_date), one invoice is generated per missed period: the first right away, the rest roughly one per hour after that.

pay and send are attempts made for each generated invoice, payment first. pay tries to charge the client's default saved card; a failed charge leaves that invoice unpaid and, if the client has a saved card, notifies the account. send tries to email the invoice to the client; if it can't be sent, the invoice is still generated with sent_at: null. Neither ever fails the request that generated the invoice.

A subscription's client and start_date can't be changed. To move the schedule, change next_invoice_at instead. Deleted subscriptions are hidden until you restore them.

View as Markdown

The subscription object

Name
id
Type
string
Description
Example: 0abcDEF1234567890xyzAB.
Name
status
Type
string
Description
One of draft, active, paused.
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
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
items[].one_time
Type
boolean
Description
Billed on the next generated invoice only, then removed from the subscription.
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
Amount in the smallest currency unit (cents). 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
Total of the next generated invoice. Example: 10000. Min 0.
Name
accept_cards
Type
boolean
Description
Whether generated invoices can be paid by card online.
Name
interval
Type
string
Description
How often to bill. biweekly is every 2 weeks, four_weeks, eight_weeks, and twelve_weeks are every 4, 8, and 12 weeks, and biannual is every 6 months. One of weekly, biweekly, four_weeks, monthly, eight_weeks, twelve_weeks, quarterly, biannual, yearly.
Name
start_date
Type
date
Description
Example: 2024-06-15.
Name
next_invoice_at
Type
date
Description
Date the next invoice will be generated. Example: 2024-07-15.
Name
number_of_invoices
Type
integer or null
Description
Number of invoices to generate before the subscription pauses automatically. null means no limit. Min 1.
Name
invoices_generated
Type
integer
Description
Number of invoices generated so far, not counting deleted ones.
Name
send
Type
boolean
Description
Email each generated invoice to the client.
Name
pay
Type
boolean
Description
Attempt to charge the client's default saved card for each generated invoice.
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 subscription object

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}

GET/subscriptions

List subscriptions

Query parameters

Name
search
Type
string
Description
Matches notes, client name and emails, and item descriptions. Not case-sensitive. Example: retainer.
Name
status
Type
string
Description
One of draft, active, paused.
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

Name
200
Description
Paginated subscriptions. Returns a paginated list of subscription objects.

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/subscriptions

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

Response

{
  "data": [
    {
      "id": "0abcDEF1234567890xyzAB",
      "status": "active",
      "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": "0abcDEF1234567890xyzAB",
        "created_at": "2024-06-15T12:00:00.000000Z",
        "updated_at": "2024-06-15T12:00:00.000000Z",
        "is_deleted": false
      },
      "currency": "usd",
      "language": "en",
      "notes": null,
      "items": [
        {
          "description": "Monthly retainer",
          "amount": 10000,
          "quantity": "1",
          "total": 10000,
          "one_time": false
        }
      ],
      "discounts": [],
      "discount_amount": 0,
      "taxable_amount": 10000,
      "tax_rates": [],
      "tax_amount": 0,
      "subtotal": 10000,
      "total": 10000,
      "accept_cards": true,
      "interval": "monthly",
      "start_date": "2024-06-15",
      "next_invoice_at": "2024-07-15",
      "number_of_invoices": null,
      "invoices_generated": 1,
      "send": true,
      "pay": true,
      "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/subscriptions

Create a subscription

Creates a draft subscription, or an active one with activate: true. Pass client_id for an existing client, or a client object to create one, but not both.

When activated with a start_date of today or earlier, the first invoice is generated immediately (and sent / paid per send and pay). A failed payment does not fail the request. A past start_date also generates one invoice per missed period after that, roughly one per hour.

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
start_date
Type
date
Required
required
Description
Date of the first invoice.
Name
number_of_invoices
Type
integer or null
Description
Number of invoices to generate before the subscription pauses automatically. Omit it or send null for no limit. Min 1.
Name
activate
Type
boolean
Description
Create the subscription active instead of draft. 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
items[].one_time
Type
boolean
Description
Bill this item on the next generated invoice only (e.g. a setup fee). At least one item must be recurring. Default: false.
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
interval
Type
string
Required
required
Description
How often to bill. biweekly is every 2 weeks, four_weeks, eight_weeks, and twelve_weeks are every 4, 8, and 12 weeks, and biannual is every 6 months. One of weekly, biweekly, four_weeks, monthly, eight_weeks, twelve_weeks, quarterly, biannual, yearly.
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 subscription 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 subscription. A tax rate is never applied twice. Default: false.
Name
accept_cards
Type
boolean
Required
required
Name
send
Type
boolean
Description
Email each generated invoice to the client. Default: false.
Name
pay
Type
boolean
Description
Attempt to charge the client's default saved card for each generated invoice. A failed charge leaves that invoice unpaid. Default: false.
Name
notes
Type
string or null

Response

Name
201
Description
Created subscription. Returns a subscription 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
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/subscriptions

curl -X POST https://api.tallymark.com/subscriptions \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "client": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": 1
    },
    {
      "description": "Setup fee",
      "amount": 5000,
      "quantity": 1,
      "one_time": true
    }
  ],
  "interval": "monthly",
  "start_date": "2027-01-01",
  "currency": "usd",
  "language": "en",
  "accept_cards": true,
  "activate": true,
  "send": true,
  "pay": true
}'

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}

GET/subscriptions/{id}

Show a subscription

Path parameters

Name
id
Type
string
Required
required
Description
The subscription ID. Example: 0abcDEF1234567890xyzAB.

Response

Name
200
Description
Subscription. Returns a subscription 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
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/subscriptions/{id}

curl https://api.tallymark.com/subscriptions/0abcDEF1234567890xyzAB \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}

POST/subscriptions/{id}/update

Update a subscription

Updates a subscription in any status. Only the fields you send are changed; omitted fields keep their current value. Send notes: null to clear the notes, number_of_invoices: null for no limit, and discounts: [] or tax_rates: [] to remove them. Changes apply to invoices generated from now on, not to invoices already generated. The client and start_date can't be changed.

If the subscription is active and the new next_invoice_at is today or earlier, the next invoice is generated immediately, and any other missed periods after that, roughly one per hour.

Path parameters

Name
id
Type
string
Required
required
Description
The subscription ID. Example: 0abcDEF1234567890xyzAB.

Request body

Send at most one discount.

Name
next_invoice_at
Type
date
Description
Date the next invoice will be generated.
Name
number_of_invoices
Type
integer or null
Description
Number of invoices to generate before the subscription pauses automatically. Send null for no limit; omit it to keep the current value. Min 1.
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
items[].one_time
Type
boolean
Description
Bill this item on the next generated invoice only (e.g. a setup fee). At least one item must be recurring. Default: false.
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
interval
Type
string
Description
How often to bill. biweekly is every 2 weeks, four_weeks, eight_weeks, and twelve_weeks are every 4, 8, and 12 weeks, and biannual is every 6 months. One of weekly, biweekly, four_weeks, monthly, eight_weeks, twelve_weeks, quarterly, biannual, yearly.
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 subscription 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 subscription. A tax rate is never applied twice. Default: false.
Name
accept_cards
Type
boolean
Name
send
Type
boolean
Description
Email each generated invoice to the client. Default: false.
Name
pay
Type
boolean
Description
Attempt to charge the client's default saved card for each generated invoice. A failed charge leaves that invoice unpaid. Default: false.
Name
notes
Type
string or null

Response

Name
200
Description
Updated subscription. Returns a subscription 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
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/subscriptions/{id}/update

curl -X POST https://api.tallymark.com/subscriptions/0abcDEF1234567890xyzAB/update \
  -H "Authorization: Bearer $TALLYMARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 12000,
      "quantity": 1
    }
  ],
  "next_invoice_at": "2024-08-01"
}'

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}

POST/subscriptions/{id}/pause

Pause a subscription

Pauses an active subscription: no invoices are generated until it is activated again.

Path parameters

Name
id
Type
string
Required
required
Description
The subscription ID. Example: 0abcDEF1234567890xyzAB.

Response

Name
200
Description
Paused subscription. Returns a subscription object.

Errors

Name
400
Type
subscription_draft
Description
This subscription is a draft and cannot be paused. Only active subscriptions can be paused.
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/subscriptions/{id}/pause

curl -X POST https://api.tallymark.com/subscriptions/0abcDEF1234567890xyzAB/pause \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}

POST/subscriptions/{id}/activate

Activate a subscription

Activates a draft or resumes a paused subscription. If next_invoice_at is today or earlier, the next invoice is generated immediately (and sent / paid per send and pay), and any other missed periods after that, roughly one per hour. Check next_invoice_at before resuming a subscription paused for longer than a billing period.

To resume a subscription that has generated all of its number_of_invoices, raise number_of_invoices first.

Path parameters

Name
id
Type
string
Required
required
Description
The subscription ID. Example: 0abcDEF1234567890xyzAB.

Response

Name
200
Description
Active subscription. Returns a subscription object.

Errors

Name
400
Type
subscription_ended
Description
This subscription has generated all of its invoices and cannot be activated. Increase number_of_invoices first.
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/subscriptions/{id}/activate

curl -X POST https://api.tallymark.com/subscriptions/0abcDEF1234567890xyzAB/activate \
  -H "Authorization: Bearer $TALLYMARK_API_KEY"

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}

POST/subscriptions/{id}/delete

Delete a subscription

Deletes a subscription. An active subscription is paused first. Invoices it already generated are not affected. You can restore it later.

Path parameters

Name
id
Type
string
Required
required
Description
The subscription ID. Example: 0abcDEF1234567890xyzAB.

Response

Name
200
Description
Deleted subscription (is_deleted true). Returns a subscription 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/subscriptions/{id}/delete

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

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}

POST/subscriptions/{id}/restore

Restore a deleted subscription

Restores a deleted subscription. It keeps its status (a deleted active subscription comes back paused). Activate it to resume.

Path parameters

Name
id
Type
string
Required
required
Description
The subscription ID. Example: 0abcDEF1234567890xyzAB.

Response

Name
200
Description
Restored subscription (is_deleted false). Returns a subscription 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/subscriptions/{id}/restore

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

Response

{
  "id": "0abcDEF1234567890xyzAB",
  "status": "active",
  "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": "0abcDEF1234567890xyzAB",
    "created_at": "2024-06-15T12:00:00.000000Z",
    "updated_at": "2024-06-15T12:00:00.000000Z",
    "is_deleted": false
  },
  "currency": "usd",
  "language": "en",
  "notes": null,
  "items": [
    {
      "description": "Monthly retainer",
      "amount": 10000,
      "quantity": "1",
      "total": 10000,
      "one_time": false
    }
  ],
  "discounts": [],
  "discount_amount": 0,
  "taxable_amount": 10000,
  "tax_rates": [],
  "tax_amount": 0,
  "subtotal": 10000,
  "total": 10000,
  "accept_cards": true,
  "interval": "monthly",
  "start_date": "2024-06-15",
  "next_invoice_at": "2024-07-15",
  "number_of_invoices": null,
  "invoices_generated": 1,
  "send": true,
  "pay": true,
  "created_at": "2024-06-15T12:00:00.000000Z",
  "updated_at": "2024-06-15T12:00:00.000000Z",
  "is_deleted": false
}