Orb

Automate the usage metering from Orb to all cloud marketplaces.


Overview

If you’re currently dependent on Orb for your metering and billing services and are aiming to grow your presence in cloud marketplaces, Fours presents the perfect solution to bridge this transition. Through our no-code, fully automated integration, you can effortlessly measure usage within your existing Orb setup and allocate it to clients across various cloud marketplaces. This integration eliminates the necessity for migration or complex engineering work, ensuring a seamless and trouble-free process.

Create Integration

In your Fours Console Integration, you will see the Orb integration connection. Click the Connect button to create an integration with your Orb instance. This will open an dialog for you to input

  • API Key: The Orb API key can be issued in the Orb’s console. Here is the auth guidance.
  • Billing Mode: quantity, amount, or invoice. If it is quantity, Fours fetch & report the billable metrics by quantity. If it is amount, Fours fetch & report the billable metrics by amount/cost. If it is invoice, Fours reports each issued Orb invoice’s total to the cloud marketplace once. See Billing Mode for details.
Orb integration connection dialog with API key and billing mode

Once the integration process is finished, you can proceed by clicking the VERIFY button. This action triggers the Fours service to test the connection to the APIs of your Orb instance. If everything is configured correctly, the integration status will be updated as VERIFIED.

Edit Integration

Editing an existing Orb integration is supported. Click the Edit button to open the dialog of editing Orb integration as shown below.

  • Enable Auto Report Usage. You can choose to enable or disable the automatic usage report feature for Orb. Enabling this feature allows Fours to run a cron job once a day to retrieve the aggregated subscription usages, costs, or issued invoice totals from Orb and report them as UsageRecordGroups to the Fours metering API. On the other hand, disabling this feature means that no cron job will be scheduled for this purpose.

  • Enable Auto Report Credit. Shown only when Billing Mode is amount and Auto Report Usage is enabled. When enabled, Fours nets out the prepaid Orb credits a buyer consumes. For each reporting window, Fours reads the credit Orb applied and subtracts it from the amount metered to the cloud marketplace.

  • Billing Mode: quantity, amount, or invoice. If it is quantity, Fours fetch the billable metrics by quantity. If it is amount, Fours fetch the billable metrics by amount/cost. If it is invoice, Fours reports each issued Orb invoice’s total to the cloud marketplace once.

  • Custom Field Concurrent Agreement ID. Optional. The name of the Orb subscription metadata field that holds the ID of the entitlement each subscription bills, its Fours entitlement ID or its marketplace ID, for example fours_entitlement_id. Fours reads it only for a buyer whose entitlements that could take the same usage are active at the same time. Leave it empty to turn this routing off. See Concurrent agreements.

  • Plans. All available price plans in your Orb instance. The source dimension keys with the price for each type of price plans can be found here.

  • Billable Metrics. The full list of billable metrics fetched from Orb for all available Orb customers. It is auto fetched from Orb, not editable.

Delete Integration

The Orb integration can be deleted like all other integrations. Once the deletion is triggered, all integration info including the API Key will be deleted immediately & permanently from Fours. No time window or methods to recover.

Billing Mode

There are three billing modes available for Fours-Orb integration: quantity, amount, and invoice. In every mode, Fours never reports to a fixed-fee entitlement, because it has no usage pricing: a fixed-fee entitlement is left out when Fours picks among a buyer’s entitlements, and a buyer whose entitlements are all fixed-fee is skipped without failing the run.

  • quantity: Fours fetches the per-period usage quantities of each billable metric from each of the buyer’s active Orb subscriptions and reports them to the mapped cloud marketplace dimensions. Only plans priced per unit or by matrix can be reported this way; for other pricing models, use amount. Each subscription’s usage goes to an entitlement that takes all of its metrics: each must match a dimension on it, directly or through dimension mapping. An Oracle entitlement also accepts new keys, as long as they fit within Fours’ limit of 100 usage keys; it is used this way only when no entitlement takes all the metrics as they are. If none can take them all, Fours still picks one entitlement (see Which entitlement gets the usage) and checks each day against it — the keys an earlier day registers on an Oracle entitlement use up room for the days after it. A day with a metric the entitlement can’t take is held back and the buyer counts as failed; the other days are still reported.
  • amount: Fours fetches the per-period costs of each of the buyer’s active Orb subscriptions and reports them on the single source dimension key orb (unit price $1). They go to one of the buyer’s entitlements that carries orb: either the entitlement has a dimension keyed or named orb, or — with Enable Dimension Mapping turned on for that marketplace in Metering Dimension Conversion — it has the dimension orb is mapped to. If none of them does, an Oracle entitlement still under Fours’ limit of 100 usage keys is used instead: Fours registers orb on it with the first report (see Usage keys are open). If no entitlement qualifies, that buyer’s usage is not reported for the run. Other buyers’ usage still is, and the run then ends as failed so the skipped buyer is not mistaken for a successful report (see Troubleshoot a failed sync). If more than one qualifies, see Which entitlement gets the usage.
  • invoice: Fours fetches each issued Orb invoice’s total and reports them on the single source dimension key orb. See Invoice Mode below.

The following table details how to configure the source dimension keys in metering dimension conversion for the quantity and amount modes.

Price Examplequantityamount
Unit
  • compute: $0.02/unit
  • storage: $0.03/unit
  • compute: $0.02/unit
  • storage: $0.03/unit
  • orb: $1/unit
Tiered
  • compute: $0.02/unit in range[0, 100)
  • compute: $0.01/unit in range[100, ∞)
  • 🚫 not supported
  • orb: $1/unit
Bulk
  • compute: $0.03/unit up to 100
  • compute: $0.02/unit up to 200
  • compute: $0.01/unit up to ∞
  • 🚫 not supported
  • orb: $1/unit
Package
  • compute: $0.2 per 100 unit
  • 🚫 not supported
  • orb: $1/unit
BPS
  • 🚫 not supported
  • orb: $1/unit
Matrix
  • compute us-west-1 gcp: $0.01/unit
  • compute us-west-1 aws: $0.02/unit
  • compute us-west-2 gcp: $0.03/unit
  • compute us-west-2 aws: $0.04/unit
  • compute__matrix__us-west-1__gcp: $0.01/unit
  • compute__matrix__us-west-1__aws: $0.02/unit
  • compute__matrix__us-west-2__gcp: $0.03/unit
  • compute__matrix__us-west-2__aws: $0.04/unit
  • orb: $1/unit

Which entitlement gets the usage

In quantity and amount modes, Fours sends each Orb subscription’s usage to one of the buyer’s entitlements that can take it, as described for each mode above:

  • One can: the usage goes to it.
  • Several can, one after another: their terms don’t overlap, so the usage goes to the one that started last. A renewal that starts exactly when the old entitlement ends is not an overlap.
  • Two or more are active at the same time: their terms overlap, so the buyer has concurrent agreements. The usage goes to the entitlement the subscription names; see Concurrent agreements.

Usage from several subscriptions that goes to the same entitlement is added up into one report per day.

Invoice Mode

In invoice mode, Fours reports issued Orb invoice totals.

During each sync run, Fours fetches the invoices of the connected Orb Customers from the last two calendar months and handles each invoice by its status:

  • Issued: The invoice’s total amount is reported to the cloud marketplace exactly once. After reporting, Fours stamps the Orb invoice with metadata suger_usage_record_group_id.
  • Void: If a voided invoice was previously reported, Fours automatically credits the reported amount back to the buyer’s entitlement.
  • Draft / Paid / Synced: Skipped.

Fours first keeps only the buyer’s entitlements that can take the orb amount, as in amount mode: a dimension keyed or named orb, or the dimension orb is mapped to; only when none has one, an Oracle entitlement with room for a new usage key.

  • None can: the buyer fails before any of its invoices is reported.
  • One can: every issued invoice goes to it.
  • Several can: each issued invoice goes to the one whose term contains the end of the invoice’s service period. A renewal that starts exactly when the old entitlement ends is not an overlap: an invoice that ends on that boundary goes to the newer one. If none of their terms contains that end, the invoice isn’t reported. That fails the buyer only while two of the entitlements that can take the orb amount have overlapping terms; otherwise Fours skips the invoice without failing the buyer.
  • Two that contain that end have overlapping terms: the buyer has concurrent agreements, and the invoice goes to the entitlement its Orb subscription names; see Concurrent agreements. If Fours can’t tell which one that is, the invoice isn’t reported and the buyer fails; the buyer’s other invoices are still reported.

Concurrent agreements

When the terms of two entitlements that can take the same Orb usage overlap, for example AWS Concurrent Agreements for the same product, bill each agreement through its own Orb subscription and tell Fours which entitlement each subscription bills:

  1. In Orb, give each of the buyer’s subscriptions the same metadata field, for example fours_entitlement_id, and set its value to the ID of the entitlement that subscription bills: its Fours entitlement ID or its marketplace ID. Orb keeps metadata as key/value pairs on the subscription; see Orb’s Update subscription reference.
  2. In Fours, open the Orb integration’s Edit dialog and enter that field’s name in Custom Field Concurrent Agreement ID.

Fours then sends a subscription’s usage that could go to entitlements whose terms overlap, or in invoice mode an invoice whose service period ends inside the terms of both, to the one the field names. That usage isn’t reported, and the buyer fails, when:

  • Custom Field Concurrent Agreement ID is empty,
  • the subscription has no value in that field, or
  • the value matches none of the entitlements that could take the usage.

The buyer’s other subscriptions and invoices are still reported. Fours ignores the field when only one entitlement can take the usage, or when the entitlements follow one another, so a buyer without concurrent agreements needs nothing set.

Setting or changing the field, or a subscription’s metadata, never reports usage twice: Fours skips each day of a subscription’s usage, and each invoice, that it has already reported, and a reported day or invoice stays on the entitlement it went to.

Connect Orb Customer

To enable Fours to fetch and report the billable metrics of Orb Customers to the appropriate entitlements in Cloud Marketplace, you need to connect the Buyer in Fours with the corresponding Customer in Orb. Simply click the Edit button in the Buyer and add the corresponding Orb Customer ID. This setup only needs to be done once; afterward, Fours’ service will automatically retrieve the latest billable metrics and report them to the correct Cloud Marketplace entitlements.

Troubleshoot a failed sync

Fours reports each buyer separately, so one buyer’s problem doesn’t stop the others, but any buyer that can’t be reported makes the run end as failed. Open Operations from the Orb card’s ⋯ menu in Settings → Integration, then hover the run’s Failed status to read why, or click its View details icon. The reason gives a count, for example Orb usage wasn’t reported for 2 of 40 buyers. Contact Fours support for more details. A run that fails for any other reason reads Internal error. Contact Fours support for more details. The console doesn’t list the buyers or what went wrong for each: Fours keeps that in its logs, so contact Fours support to find out which buyers failed and why. The table below lists the common causes and the fix for each.

Common causeWhat to do
None of the buyer’s metering entitlements carries the orb dimension (amount and invoice modes)Add the usage dimension that orb is mapped to in Metering Dimension Conversion to the offer, then ask Fours support to add that dimension to the entitlement.
Two of the buyer’s entitlements that could take the usage are active at the same time, and the Orb subscription doesn’t name one of themSet Custom Field Concurrent Agreement ID, and give each of the buyer’s Orb subscriptions that metadata field with the ID of the entitlement it bills. See Concurrent agreements.
The entitlement is missing some usage dimensions, so some days weren’t reported (quantity mode)Add the missing dimensions to the offer as usage dimensions, then ask Fours support to add them to the entitlement.
The Oracle entitlement already has too many of its 100 usage dimensions to take the new ones, so some days weren’t reported (quantity mode)Ask Fours support to remove the entitlement’s unused usage dimensions.
One of the buyer’s active Orb subscriptions has no planAttach a plan to the subscription in Orb.
The plan’s pricing can’t be reported as quantities (quantity mode)Use unit or matrix pricing on the plan, or switch the integration to the amount billing mode.
Orb has no customer with the ID the buyer is linked toLink the buyer to its current Orb customer (see Connect Orb Customer), or unlink it if it no longer uses Orb.
Orb rejected the API keyConnect Orb again with a valid key. The edit dialog has no API key field, so delete the integration, create it again, and turn its settings back on.
Orb rate-limited the requests, or Orb was unavailableNothing — the next sync tries again.
The buyer’s prepaid Orb credits couldn’t be appliedThe usage was reported without the credits, and the next sync tries again. Contact Fours support if it keeps happening.
An internal errorThe next sync tries again. Contact Fours support if it keeps failing.

Spotted something wrong or out of date on this page? Tell us and we'll correct it.