API reference

Billing

The plan the company is on, the monthly spend it is priced by, the price list, and the Stripe pages that start or change it.

GET/v1/billingGet the plan, the monthly spend it is priced by, and the subscription
POST/v1/billing/checkout_sessionsStart a paid plan on a Stripe Checkout page
GET/v1/billing/plansList the plans and their prices
POST/v1/billing/portal_sessionsOpen the Stripe portal for the card, invoices or cancelling
PUT/v1/billing/yc_offerClaim the YC offer with a founder's verification link
DELETE/v1/billing/yc_offerTake back the YC offer before it starts
POST/v1/billing/yc_offer/checkRead a founder's YC verification link

Guides: Billing and your plan

Get the plan, the monthly spend it is priced by, and the subscription

GET/v1/billing

client.billing.get()

The organization's plan, the monthly spend it is priced by, and its subscription as of the last webhook from Stripe.

Response

200BillingOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/billing" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Start a paid plan on a Stripe Checkout page

POST/v1/billing/checkout_sessions· Idempotent

client.billing.createCheckoutSession()

Start a paid plan: a Stripe Checkout page for the plan the monthly spend calls for, or a bigger one, with a line for each set of books beyond the first. A YC company's page carries the offer. Refused with plan_is_free for Starter, plan_below_spend for a plan the spend is over, and already_subscribed while a subscription stands — change that one through the portal instead.

Request body

CheckoutIn

Response

201SessionOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/billing/checkout_sessions" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

List the plans and their prices

GET/v1/billing/plans

client.billing.listPlans()

The price list: each plan's price, monthly and yearly, and the monthly spend it covers.

Response

200PlanListOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/billing/plans" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Open the Stripe portal for the card, invoices or cancelling

POST/v1/billing/portal_sessions· Idempotent

client.billing.createPortalSession()

Open the Stripe customer portal: payment method, invoices, cancelling.

Response

201SessionOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/billing/portal_sessions" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Claim the YC offer with a founder's verification link

PUT/v1/billing/yc_offer

client.billing.setYcOffer()

Claim the YC offer with a founder's verification link. LedgerIt reads the link from Y Combinator: YC must vouch for the founder (yc_link_invalid otherwise), the link must show company details (yc_company_hidden), one company must be meant (yc_company_required when the link names several and company is not given), and that company must not have the offer on another LedgerIt account already (yc_company_claimed). The batch is the company's. Before a paid plan, checkout then applies the offer: Founder free for 12 months, then half price for 12, or Founder's price off a bigger plan. On a paid plan already, the offer starts on the next billing date. Naturally idempotent: the same link twice is one offer. Once the offer has started, a different batch is refused with yc_offer_started.

Request body

YcOfferIn

Response

200BillingOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PUT "https://api.ledgerit.ai/v1/billing/yc_offer" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"verification_url":"…"}'

Take back the YC offer before it starts

DELETE/v1/billing/yc_offer

client.billing.removeYcOffer()

Take back the YC offer before it starts, with the verification behind it. Once a subscription carries it, it is refused with yc_offer_started. Naturally idempotent.

Response

204No content

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X DELETE "https://api.ledgerit.ai/v1/billing/yc_offer" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Read a founder's YC verification link

POST/v1/billing/yc_offer/check

client.billing.checkYcLink()

Read a founder's YC verification link without claiming anything: whether Y Combinator vouches for them, and the companies and batches the link shows, each marked when another LedgerIt account already took the offer with it. A link YC does not know is refused with yc_link_invalid; when YC does not answer, yc_unavailable.

Request body

YcLinkIn

Response

200YcLinkCheckOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/billing/yc_offer/check" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"verification_url":"…"}'

Objects

The objects these operations take and return.

BillingOut

What the organization behind these books pays for LedgerIt.

Name	Type	Description
`billing_period`Required	string or null	`monthly` or `yearly`; null on Starter.
`cancel_at_period_end`Required	boolean	The subscription is cancelled and ends at `current_period_end`.
`configured`Required	boolean	Whether this server can take payments at all. False means checkout and the portal will answer `billing_unconfigured`.
`current_period_end`Required	string (date-time) or null	When the current paid period ends — the next renewal, the last day of service if `cancel_at_period_end`, or when service ended for a `canceled` subscription.
`entities`Required	integer	Sets of books the organization keeps.
`extra_entities`Required	integer	Sets of books beyond the first the subscription bills.
`has_customer`Required	boolean	Whether the organization has a Stripe customer, i.e. whether the billing portal can be opened.
`offer`Required	yc_terms or null	The offer the organization is owed through its referral: `yc_terms` (the YC offer, applied at checkout without a batch) for a fund's or an accelerator's company. Null for none.
`paid`Required	boolean	True while the subscription is active or trialing.
`pending_plan`Required	string or null	A plan the organization moves to after months over its ceiling.
`pending_plan_at`Required	string (date-time) or null	The billing date that move takes effect on.
`plan`Required	string or null	The plan the organization is on: `starter` without a subscription, else the subscription's (`founder`, `growth`, `scale`). Null for a subscription on a price that is no plan's.
`referral`Required	ReferralOut or null	The partner the organization signed up through, or null (decision 0130).
`required_plan`Required	string	The cheapest plan the monthly spend and the number of sets of books fit. Checkout sells it, or a bigger plan the owner chooses.
`spend`Required	SpendOut
`status`Required	string or null	The Stripe subscription status (`active`, `trialing`, `past_due`, `canceled`, …), or null if the organization has never subscribed.
`wholesale_rate`Required	string or null	Off a plan's list price, as a fraction (0.20 is 20%), for a firm's client. Not applied by checkout yet: firms' clients are billed by hand. Null for none.
`yc_offer`Required	YcOfferOut or null	The YC offer, once a batch is given or when the organization came through a fund's or an accelerator's link.

CheckoutIn

Name	Type	Description
`billing_period`	string	`monthly`, or `yearly` for ten months' price paid once a year. Default monthly
`plan`	string or null	The plan to buy. Leave it out for the one the spend calls for (`required_plan`); a smaller one is refused with `plan_below_spend`.

SessionOut

A Stripe-hosted page to send the person to.

Name	Type	Description
`url`Required	string	The page on stripe.com. Valid for a short time; open it now.

PlanListOut

The price list (decision 0126).

Name	Type	Description
`currency`Required	string	Always `USD`.
`data`Required	array of PlanOut
`extra_entity_monthly_price`Required	string	Each set of books beyond the first on a paid plan, a month.
`spend_window_months`Required	integer	Months the spend is averaged over, and months in a row over a ceiling before a plan moves up.
`trial_days`Required	integer	Days free on an organization's first paid plan.

YcOfferIn

Name	Type	Description
`company`	string or null	Which of the link's companies these books are for, by its `directory_url` from `billing.check_yc_link`. Needed only when the link names several; refused with `yc_company_required` otherwise.
`verification_url`Required	string	A founder's YC verification link, `https://www.ycombinator.com/verify/<code>`, made at ycombinator.com/verify/manage with company details shown. Never logged or returned: it is the founder's proof.

YcLinkIn

Name	Type	Description
`verification_url`Required	string	A founder's YC verification link, `https://www.ycombinator.com/verify/<code>`, made at ycombinator.com/verify/manage with company details shown. Never logged or returned: it is the founder's proof.

YcLinkCheckOut

What a founder's verification link proves, read from Y Combinator.

Name	Type	Description
`companies`Required	array of YcCompanyOut	The companies the founder chose to show. Empty when the link shows the batch only: claiming needs company details.
`founder_name`Required	string or null	The founder's name as YC gives it.
`verified`Required	boolean	Whether Y Combinator vouches for the link's holder.

ReferralOut

Who the organization came to LedgerIt through (decision 0130).

Name	Type	Description
`partner_name`Required	string or null	The partner's name; null if LedgerIt no longer lists the partner.
`program`Required	string	`fund`, `accelerator` or `firm`. One of `fund`, `accelerator`, `firm`

SpendOut

The monthly spend the plan is priced by.

Name	Type	Description
`average`Required	string or null	Money out averaged over `months`: the monthly spend. Null when the books have no complete month yet.
`currency`Required	string	Always `USD`: plans are priced in US dollars.
`months`Required	array of SpendMonthOut	The complete months averaged, oldest first — at most `window_months`. Transfers between the company's own accounts, moves to savings and loan principal are not spend.
`months_over_ceiling`Required	integer	How many of the latest months in a row were over the current plan's ceiling. The plan moves up when this reaches `window_months`.
`window_months`Required	integer	How many months the spend is averaged over.

YcOfferOut

Name	Type	Description
`batch`Required	string or null	The Y Combinator batch the offer was claimed with, like `W26`, read from the founder's verification link; null when the offer came with a partner's link instead (see `referral`).
`company_name`Required	string or null	The YC company the link named, as YC's directory lists it; null for a batch given before verification links (decision 0183) or a partner's referral.
`company_url`Required	string or null	The company's page in YC's public directory, `https://www.ycombinator.com/companies/<slug>`; null with `company_name`.
`starts_at`Required	string (date-time) or null	The billing date the offer's first year starts on; null until a subscription carries it.
`verified_at`Required	string (date-time) or null	When Y Combinator vouched for the link; null with `company_name`.
`year`Required	integer or null	Which year of the offer it is now: 1 (Founder's price off), 2 (half of it off), or null before or after.

PlanOut

One plan on the price list.

Name	Type	Description
`entities_included`Required	integer or null	Sets of books included; null when every set beyond the first is an add-on.
`id`Required	string	`starter`, `founder`, `growth` or `scale`, cheapest first.
`monthly_price`Required	string	US dollars a month on monthly billing; Scale's is where it starts.
`spend_ceiling`Required	string or null	The most monthly spend the plan covers, in US dollars; null for none.
`yearly_price`Required	string	US dollars for a year paid up front: ten months.

YcCompanyOut

A company on a verification link, as YC's directory lists it.

Name	Type	Description
`batch`Required	string	Its batch, like `W23`.
`claimed`Required	boolean	Another LedgerIt account already took the YC offer with this company; claiming it again is refused with `yc_company_claimed`.
`directory_url`Required	string	Its page in YC's public directory. Pass it as `company` to `billing.set_yc_offer`.
`name`Required	string	The company's name.
`url`Required	string or null	The company's own site, when YC lists one.

SpendMonthOut

Name	Type	Description
`amount`Required	string	Money out in the month, in US dollars.
`month`Required	string (date)	The first day of the month.