Mark an invoice paid: received by bank transfer

POST

/billing/admin/orgs/{orgId}/invoices/{invoiceId}/paid

curl --request POST \
  --url https://api.sloose.com/billing/admin/orgs/org_9f3c/invoices/in_1Abc/paid \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "amount": 1, "receivedOn": "example", "reference": "example", "note": "example" }'

• Production
• Staging

Backoffice route: a staff session, or ADMIN_TOKEN; never a customer’s session. Records a transfer received against one of the org’s open invoices billed by invoice, and marks it paid out of band at Stripe, which sends invoice.paid through the flow every payment takes. The transfer — when it arrived, its reference, the amount, and the note — is written on the invoice’s metadata at Stripe too. Stripe “paid” means we consider it settled: an amount other than what is owed needs a note saying why it settles it (a fee or an exchange shortfall absorbed). Whether a shortfall is small enough to absorb is the person’s judgement; nothing here measures it. Written down as org.invoice_paid.

Authorizations

• sessionAuth
• adminToken

Parameters

Path Parameters

orgId

required

The org id.

string

Example

org_9f3c

The org id.

invoiceId

required

The Stripe invoice id.

string

Example

in_1Abc

The Stripe invoice id.

Request Body^required

Media typeapplication/json

object

amount

What arrived, in cents of the invoice’s currency.

number

receivedOn

YYYY-MM-DD.

string

reference

string

note

string | null

key

additional properties

Example^generated

{
  "amount": 1,
  "receivedOn": "example",
  "reference": "example",
  "note": "example"
}

Responses

200

Marked paid.

Media typeapplication/json

object

invoiceId

required

string

number

required

string | null

owed

required

number

amount

required

number

difference

required

What arrived less what was owed: negative is short.

number

currency

required

string

Example^generated

{
  "invoiceId": "example",
  "number": "example",
  "owed": 1,
  "amount": 1,
  "difference": 1,
  "currency": "example"
}

400

The request is not one this can make, or the amount differs with no note (DIFFERENCE_NEEDS_NOTE).

Media typeapplication/json

object

error

required

string

code

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

401

A bearer that is neither the token nor a live session (code: AUTH_REQUIRED).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

403

A customer’s session, an API token, or no bearer at all — not staff, and not the ADMIN_TOKEN (code: ADMIN_REQUIRED).

Media typeapplication/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

404

No such invoice of this org’s (INVOICE_NOT_FOUND).

Media typeapplication/json

object

error

required

string

code

required

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

409

Not waiting for payment (INVOICE_NOT_OPEN), or charged to a card (NOT_INVOICE_BILLED).

Media typeapplication/json

object

error

required

string

code

required

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

502

Stripe refused the request (PAYMENT_PROVIDER_REFUSED) — nothing was charged, though a step taken before the refusal stands: the org’s first Stripe customer, or an existing customer’s billing email brought up to date — or was unavailable (PAYMENT_PROVIDER_UNAVAILABLE: unreachable, failing or rate-limiting), which may or may not have gone through — check before retrying. Stripe’s own words are logged, not returned.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: PAYMENT_PROVIDER_REFUSED PAYMENT_PROVIDER_UNAVAILABLE

key

additional properties

Example

{
  "code": "PAYMENT_PROVIDER_REFUSED"
}