OrbitsDocs
esc
    Open Orbits
    API reference · TeamBilling

    Billing

    The plans, the team's plan and what it includes, and its invoices.

    Read which plan a team is on, what it includes, and its invoices. Paying, cancelling and resuming happen in the dashboard, by an owner: an API token may read billing but never change it. See Plans.

    The billing object

    Fields

    • planstringrequired

      One of free, pro.

    • statusstringrequired

      past_due: Pro, but the period has ended unpaid and the team is in its grace period.

      One of free, active, past_due.

    • sourcestring or nullrequired

      comp: Pro granted by Orbits, nothing to pay. Null on Free.

      One of flutterwave, comp.

    • enforcedbooleanrequired

      Whether plan limits are switched on. When false every feature works for every team.

    • current_periodnull or objectrequired
      Show 2 child fields
      • startstringrequired
      • endstring or nullrequired

        Null for a plan with no end (comp).

    • cancel_at_period_endbooleanrequired
    • grace_ends_atstring or nullrequired
    • priceobjectrequired

      Pro's price today, for the upgrade button.

      Show 3 child fields
      • usd_centsintegerrequired
      • ngninteger or nullrequired
      • ratestring or nullrequired
    • next_chargenull or objectrequired
      Show 2 child fields
      • usd_centsintegerrequired
      • ngninteger or nullrequired
    • entitlementsobjectrequired

      What this team may do now. All true (and sleeps_when_idle false) while enforced is false.

      Show 5 child fields
      • functionsbooleanrequired
      • sandboxesbooleanrequired
      • analyticsbooleanrequired
      • speed_insightsbooleanrequired
      • sleeps_when_idlebooleanrequired
    • cardnull or objectrequired
      Show 3 child fields
      • brandstring or nullrequired
      • last4stringrequired
      • expstring or nullrequired
    • can_managebooleanrequired

      True for owners, who may change billing.

    • bannernull or BillingAlertrequired

      The owners' notice about the plan, or null. Always null for members.

      Show 6 child fields
      • kindstringrequired

        Always downgraded.

      • atstring
      • amount_ngninteger or null
      • chargestring

        One of automatic, manual.

      • grace_ends_atstring
      • ends_atstring

    The invoice object

    Fields

    • idstringrequired
    • kindstringrequired

      A first purchase, an automatic renewal, or a payment made by hand while already Pro or past due.

      One of initial, renewal, manual.

    • statusstringrequired

      One of open, paid, failed, void.

    • usd_centsintegerrequired

      The dollar price.

    • ngn_amountintegerrequired

      Whole Naira charged: the dollar price at fx_rate, rounded up to a whole ₦100, locked when the invoice was made.

    • fx_ratestringrequired

      The USD → NGN rate it was converted at.

    • periodobject or nullrequired

      The month it paid for; null until it is paid.

      Show 2 child fields
      • startstringrequired
      • endstringrequired
    • referencestringrequired
    • methodstring or nullrequired

      How it was paid; null until it is.

      One of card, bank_transfer, other.

    • paid_atstring or nullrequired
    • created_atstringrequired

    The plans and their prices

    Orbits has two plans. Free is unlimited projects, with apps that scale to zero, and without server functions, sandboxes and Analytics or Speed Insights. Pro is usd_cents: 500 a month and has all of them. ngn is the Naira amount charged for the price: the USD price at rate (a rate Orbits sets, USD → NGN), rounded up to a whole ₦100. It is null until the server has a rate set (then Pro can't be bought yet). The amount a payment is actually taken for is locked on the invoice when checkout starts, so show ngn as "about" only if you need to hedge; POST .../billing/checkout refuses with 409 if the amount you showed no longer matches.

    features describe the plan, not the team, and are the same whether or not limits are being enforced yet (enforced on GET /v1/teams/{team}/billing says whether they are).

    GET/v1/plans
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Response 200

    The plans.
    • itemsarray of Planrequired
      Show 5 child fields
      • idstringrequired

        One of free, pro.

      • namestringrequired
      • usd_centsintegerrequired
      • ngninteger or nullrequired

        Whole Naira at the current rate, rounded up to a whole ₦100; 0 for Free; null while no rate is set.

      • featuresPlanFeaturesrequired
        Show 6 child fields
        • unlimited_projectsbooleanrequired
        • functionsbooleanrequired

          The function workload type. On Free the same frameworks (Next.js, SvelteKit, Nuxt, Remix...) run as ordinary apps.

        • sandboxesbooleanrequired
        • analyticsbooleanrequired
        • speed_insightsbooleanrequired
        • sleeps_when_idlebooleanrequired

          Apps scale to zero when idle (Free). Not running yet: Free apps stay on until that ships.

    • ratestring or nullrequired

      The USD → NGN rate in use, as a decimal string, or null when none is set.

    Errors

      Every code is explained in Errors.

      curl "https://api.theorbits.app/v1/plans" \
        -H "Authorization: Bearer $ORBITS_TOKEN"
      Response 200
      {
        "items": [
          {
            "id": "free",
            "name": "Pro",
            "usd_cents": 500,
            "ngn": 8000,
            "features": {
              "unlimited_projects": false,
              "functions": false,
              "sandboxes": false,
              "analytics": false,
              "speed_insights": false,
              "sleeps_when_idle": false
            }
          }
        ],
        "rate": "1600"
      }

      The team's plan and billing state

      What the Settings Plan card and the Billing page show: the plan, whether it is active, past_due (a payment failed and the team is in its grace period) or free, the current period, what the next charge will be, what the plan allows, and (for owners) the card on file. enforced is false while Orbits has not switched plan limits on: every feature works for every team and entitlements all say true, although plan still says what the team is on.

      Permissions: Any team member sees the plan; the card is shown to owners only. A non-member gets 404.

      GET/v1/teams/{team}/billing
      Read or full tokenReturns200OK

      Headers

      • Authorizationstringrequired

        Bearer and your API token: Bearer orb_live_….

      Path parameters

      • teamstringrequired

        Team slug or team_ id.

      Response 200

      The billing state.
      • planstringrequired

        One of free, pro.

      • statusstringrequired

        past_due: Pro, but the period has ended unpaid and the team is in its grace period.

        One of free, active, past_due.

      • sourcestring or nullrequired

        comp: Pro granted by Orbits, nothing to pay. Null on Free.

        One of flutterwave, comp.

      • enforcedbooleanrequired

        Whether plan limits are switched on. When false every feature works for every team.

      • current_periodnull or objectrequired
        Show 2 child fields
        • startstringrequired
        • endstring or nullrequired

          Null for a plan with no end (comp).

      • cancel_at_period_endbooleanrequired
      • grace_ends_atstring or nullrequired
      • priceobjectrequired

        Pro's price today, for the upgrade button.

        Show 3 child fields
        • usd_centsintegerrequired
        • ngninteger or nullrequired
        • ratestring or nullrequired
      • next_chargenull or objectrequired
        Show 2 child fields
        • usd_centsintegerrequired
        • ngninteger or nullrequired
      • entitlementsobjectrequired

        What this team may do now. All true (and sleeps_when_idle false) while enforced is false.

        Show 5 child fields
        • functionsbooleanrequired
        • sandboxesbooleanrequired
        • analyticsbooleanrequired
        • speed_insightsbooleanrequired
        • sleeps_when_idlebooleanrequired
      • cardnull or objectrequired
        Show 3 child fields
        • brandstring or nullrequired
        • last4stringrequired
        • expstring or nullrequired
      • can_managebooleanrequired

        True for owners, who may change billing.

      • bannernull or BillingAlertrequired

        The owners' notice about the plan, or null. Always null for members.

        Show 6 child fields
        • kindstringrequired

          Always downgraded.

        • atstring
        • amount_ngninteger or null
        • chargestring

          One of automatic, manual.

        • grace_ends_atstring
        • ends_atstring

      Errors

      • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

      Every code is explained in Errors.

      curl "https://api.theorbits.app/v1/teams/my-team/billing" \
        -H "Authorization: Bearer $ORBITS_TOKEN"
      Response 200
      {
        "plan": "free",
        "status": "free",
        "source": "flutterwave",
        "enforced": false,
        "current_period": {
          "start": "2026-11-10T09:30:00Z",
          "end": "2026-11-10T09:30:00Z"
        },
        "cancel_at_period_end": false,
        "grace_ends_at": "2026-11-10T09:30:00Z",
        "price": {
          "usd_cents": 1,
          "ngn": null,
          "rate": null
        },
        "next_charge": {
          "usd_cents": 1,
          "ngn": null
        },
        "entitlements": {
          "functions": false,
          "sandboxes": false,
          "analytics": false,
          "speed_insights": false,
          "sleeps_when_idle": false
        },
        "card": {
          "brand": null,
          "last4": "4471",
          "exp": "09/28"
        },
        "can_manage": false,
        "banner": {
          "kind": "upcoming",
          "at": "2026-11-10T09:30:00Z",
          "amount_ngn": null,
          "charge": "automatic"
        }
      }

      The team's invoices

      The Invoices list: payments made for Pro, newest first. Payments that were started and never paid are not listed. limit is 1 to 100 (default 25); there is no cursor yet.

      Permissions: Team owners only; other members get 403.

      GET/v1/teams/{team}/billing/invoices
      Read or full tokenReturns200OK

      Headers

      • Authorizationstringrequired

        Bearer and your API token: Bearer orb_live_….

      Path parameters

      • teamstringrequired

        Team slug or team_ id.

      Query parameters

      • limitinteger

        From 1 to 100. Defaults to 25.

      Response 200

      The invoices.
      • itemsarray of Invoicerequired
        Show 11 child fields
        • idstringrequired
        • kindstringrequired

          A first purchase, an automatic renewal, or a payment made by hand while already Pro or past due.

          One of initial, renewal, manual.

        • statusstringrequired

          One of open, paid, failed, void.

        • usd_centsintegerrequired

          The dollar price.

        • ngn_amountintegerrequired

          Whole Naira charged: the dollar price at fx_rate, rounded up to a whole ₦100, locked when the invoice was made.

        • fx_ratestringrequired

          The USD → NGN rate it was converted at.

        • periodobject or nullrequired

          The month it paid for; null until it is paid.

          Show 2 child fields
          • startstringrequired
          • endstringrequired
        • referencestringrequired
        • methodstring or nullrequired

          How it was paid; null until it is.

          One of card, bank_transfer, other.

        • paid_atstring or nullrequired
        • created_atstringrequired

      Errors

      • 403Authenticated but not allowed in this team.
      • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

      Every code is explained in Errors.

      curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices" \
        -H "Authorization: Bearer $ORBITS_TOKEN"
      Response 200
      {
        "items": [
          {
            "id": "id",
            "kind": "initial",
            "status": "open",
            "usd_cents": 1,
            "ngn_amount": 1,
            "fx_rate": "fx-rate",
            "period": {
              "start": "2026-11-10T09:30:00Z",
              "end": "2026-11-10T09:30:00Z"
            },
            "reference": "reference",
            "method": "card",
            "paid_at": "2026-11-10T09:30:00Z",
            "created_at": "2026-11-10T09:30:00Z"
          }
        ]
      }

      One invoice, as a receipt

      The invoice with who paid, for which team, what for, and the card (brand and last four) it was paid with. There is no PDF; the dashboard renders the receipt.

      Permissions: Team owners only. An invoice of another team is 404.

      GET/v1/teams/{team}/billing/invoices/{invoice}
      Read or full tokenReturns200OK

      Headers

      • Authorizationstringrequired

        Bearer and your API token: Bearer orb_live_….

      Path parameters

      • teamstringrequired

        Team slug or team_ id.

      • invoicestringrequired

        An id from GET .../billing/invoices.

      Response 200

      The receipt.
      • idstringrequired
      • kindstringrequired

        A first purchase, an automatic renewal, or a payment made by hand while already Pro or past due.

        One of initial, renewal, manual.

      • statusstringrequired

        One of open, paid, failed, void.

      • usd_centsintegerrequired

        The dollar price.

      • ngn_amountintegerrequired

        Whole Naira charged: the dollar price at fx_rate, rounded up to a whole ₦100, locked when the invoice was made.

      • fx_ratestringrequired

        The USD → NGN rate it was converted at.

      • periodobject or nullrequired

        The month it paid for; null until it is paid.

        Show 2 child fields
        • startstringrequired
        • endstringrequired
      • referencestringrequired
      • methodstring or nullrequired

        How it was paid; null until it is.

        One of card, bank_transfer, other.

      • paid_atstring or nullrequired
      • created_atstringrequired
      • teamobjectrequired
        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • payer_emailstring or nullrequired
      • descriptionstringrequired
      • cardobject or nullrequired

        The card it was paid with; null when it is unpaid or was paid by bank transfer.

        Show 3 child fields
        • brandstring or null
        • last4stringrequired
        • expstring or null

      Errors

      • 403Authenticated but not allowed in this team.
      • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

      Every code is explained in Errors.

      curl "https://api.theorbits.app/v1/teams/my-team/billing/invoices/inv_01jc8x6e4mq2v7r9y3t5b0zp8w" \
        -H "Authorization: Bearer $ORBITS_TOKEN"
      Response 200
      {
        "id": "id",
        "kind": "initial",
        "status": "open",
        "usd_cents": 1,
        "ngn_amount": 1,
        "fx_rate": "fx-rate",
        "period": {
          "start": "2026-11-10T09:30:00Z",
          "end": "2026-11-10T09:30:00Z"
        },
        "reference": "reference",
        "method": "card",
        "paid_at": "2026-11-10T09:30:00Z",
        "created_at": "2026-11-10T09:30:00Z",
        "team": {
          "id": "id",
          "slug": "my-app",
          "name": "my-app"
        },
        "payer_email": "ada@example.com",
        "description": "Orbits Pro",
        "card": {
          "brand": null,
          "last4": "last4",
          "exp": null
        }
      }

      Was this page helpful?

      Updated