# Orb Destination

## Destination Info

* Accepts [Track](/docs/segment/connections/spec/track) calls.
* Refer to it as **Orb** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)
* This integration is **partner owned.** Please reach out to the partner's support for any issues.

[Orb](https://www.withorb.com/) provides scalable, reliable, and flexible billing infrastructure for usage based revenue models at companies of all sizes.

Orb maintains this destination. For any issues with the destination, [contact the Orb support team](mailto:support@withorb.com).

## Getting started

1. Navigate to **Connections** and click **Add Destination** in the Segment app.
2. Search for *Orb* in the Destinations Catalog, and select the **Orb** destination.
3. Choose which Source should send data to the Orb destination.
4. Go to the [Orb dashboard](https://app.billwithorb.com) and create a new API key from the configuration page. Segment recommends you to create a new API key for this integration rather than using an existing one.
5. Enter the **API Key** in the Orb destination settings in Segment.
6. Enter the connection settings for the external customer ID and properties mapping fields.

## Supported methods

Orb currently supports track calls, as specified in the [Segment Spec](/docs/segment/connections/spec).

### Track

Use [Track](/docs/segment/connections/spec/track) calls to automatically send usage events based on your customer's interactions with your application. Any Segment track call will be ingested through [Orb's ingestion pipeline](https://docs.withorb.com/guides/events-and-metrics/event-ingestion) and usage information will be used to calculate billable totals. For example:

```js
analytics.track({
  event: "payment_confirmed",
  userId: "external_customer_id",
  properties: {
    amount: 100.00,
    currency: "USD",
    confirmation_time: "2022-05-11T21:33:13.1652304793Z"
  }
});
```

Similar to Segment, Orb supports a flexible event schema in the `properties` dictionary, which should be non-null and not contain nested objects. Within Orb, you can configure metrics by filtering and aggregating events. When you configure the Orb destination, you are required to specify a mapping of keys from the original Segment event to Orb's usage event. You can also configure keys corresponding to Orb's required fields such as `event_name` , `idempotency_key`, and `external_customer_id`.

Events ingested through the track spec are available on the Orb admin dashboard, specifically on the [Events page](https://app.billwithorb.com/events).

## Engage

You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo).

For user-property destinations, an [identify](/docs/segment/connections/spec/identify/) call is sent to the destination for each user being added and removed. The property name is the snake\_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to `false`.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

> \[!NOTE]
>
> Real-time audience syncs to Orb  may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.

## Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

| Field                      | Description                                                                                                                                                                                                                                                                   | Required | Type     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| API Key                    | You can generate or reuse an existing API key setup from the Orb webapp.                                                                                                                                                                                                      | Yes      | string   |
| Event name field           | Optionally specify the key in your Segment event which signifies the name of the action, which is mapped to \`event\_name\` in Orb. By default, Orb will use the value of "event".                                                                                            | No       | string   |
| External customer ID field | Specify the key in your Segment event that identifies your user. This will be used as the "external\_customer\_id" for the Orb event.                                                                                                                                         | Yes      | string   |
| Idempotency key field      | Optionally specify the key in your Segment event which uniquely identifies this event. This is mapped to "idempotency\_key" in Orb. By default, Orb will use the value of "messageId".                                                                                        | No       | string   |
| Properties mapping fields  | Map your track spec property keys from Segment to your desired event spec for Orb. If a mapping is not specified, the key will be dropped from the event before ingestion to avoid ingesting unwanted or sensitive data. All keys and values in this field should be strings. | Yes      | text-map |