Skip to content
Pealboard

Read the subscription back from Stripe

POST
/v1/billing/reconcile
curl --request POST \
  --url https://api.pealboard.com/v1/billing/reconcile \
  --header 'Authorization: Bearer <token>'

Re-reads this workspace’s subscription from Stripe and writes what it says: plan, interval, quantity, status and the trial’s end. For the case where a webhook was dropped or failed and the workspace is looking at a plan it is not on. It changes nothing in Stripe. The same repair runs nightly for every workspace, so this is the impatient version of waiting, not a different mechanism. A workspace that has never been billed has nothing to read back and is refused with a 409.

Access. Requires the owner. Reading the subscription back from Stripe and writing what it says is the owner’s, because what it writes is what the workspace is charged for. API-key scope: workspace:write.

Billing. This still works when the workspace has lapsed. A workspace that has lapsed because a delivery was dropped is exactly the workspace that needs this, and refusing it would make the defect its own defence.

Retries. Send Idempotency-Key and a retry with the same key within 24 hours returns the first answer rather than acting twice.

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

The billing, after the repair.

Media typeapplication/json
object
standing
required

Only lapsed refuses a write, with a 402. past_due still writes: Stripe is retrying and moves it on when it gives up.

string
Allowed values: free trialing active past_due lapsed
plan
required
string
Allowed values: free team business
interval
required
string | null
Allowed values: monthly annual
trialEndsAt
required
string | null format: date-time
currentPeriodEnd
required
string | null format: date-time
trialAvailable
required

A workspace may take the 14-day trial once.

boolean
billableMembers
required

Owners, admins and members. Viewers are free.

integer
quantity
required

What Stripe is currently charging for.

integer
limits
required
object
members
required
integer | null
portals
required
integer | null
repositories
required
integer | null
usage
required
object
members
required
integer
portals
required
integer
repositories
required
integer
plans
required
Array<object>
object
id
required
string
Allowed values: free team business
name
required
string
monthlyCents
required
integer
annualCentsPerMonth
required
integer
limits
required
object
members
required
integer | null
portals
required
integer | null
repositories
required
integer | null
Example
{
  "standing": "free",
  "plan": "free",
  "interval": "monthly",
  "plans": [
    {
      "id": "free"
    }
  ]
}

401

Section titled “401”

No valid credentials.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

403

Section titled “403”

Authenticated, but not permitted.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

404

Section titled “404”

No such resource, or it is not visible to you.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

409

Section titled “409”

The request conflicts with the current state.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

422

Section titled “422”

The request did not match the expected shape.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

429

Section titled “429”

Rate limited. Retry after the interval in the header.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}

502

Section titled “502”

GitHub or another dependency refused or did not answer. Nothing in the workspace changed.

Media typeapplication/json
object
error
required
object
code
required

A stable identifier for the kind of failure. Safe to branch on.

string
message
required

What went wrong, written for a person.

string
detail

Structured particulars, when there are any.

object
key
additional properties
remedy

What to do about it, when there is something to do.

string
requestId
required

Quote this when asking about a specific failure.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "detail": {
      "additionalProperty": "example"
    },
    "remedy": "example",
    "requestId": "example"
  }
}