​
Step 1: Enable Test Mode

  • When starting, use Test Mode to experiment and test your Orb setup.
  • In Test Mode, you can create test pricing plans, simulate different workflows, and send in dummy data.
  • This environment allows you to see how events and usage data will appear on invoices.

​
Step 2: Generate an API Key

  • To send events to Orb, you’ll need an API key.
  • Navigate to the Developers section in the Orb dashboard and click on API Keys.
  • Create a new API key, name it (e.g., “Test Key”). This key will interact with resources in Test Mode.

​
Step 3: Set Up Postman

  • You’ll use Postman to make API calls in this tutorial. Postman is a tool for testing APIs.
  • Once you’re ready to move into production, you can either use Orb’s SDKs or directly call the API.

​
Step 4: Construct the Event Payload

Events are key to usage tracking and calculations in Orb. When creating your payload, ensure it adheres to this format:
  • Customer ID / External Customer ID: Identifies which customer the event belongs to.
    • The Customer ID refers to the internal Orb-generated ID.
    • The External Customer ID is an alias you define.
      • If you send events with just the external ID, Orb will accept them and link them once the customer’s subscription is created.
  • Timestamp: This indicates when the event occurred.
  • Event Name: Describes the type of event (e.g., API calls, product usage).
  • Properties: Free-form key-value pairs where you can add additional information, such as regions, sources, or other event attributes.
    • Values can be strings, booleans, or numbers.
  • Idempotency Key: A unique identifier for your event to prevent duplicates.
    • If the event is sent again within a specified grace period, Orb will ignore subsequent events with the same idempotency key.
Example Payload Structure: 
{
  "events": [
    {
      "external_customer_id": "cust-001", 
      "timestamp": "2023-09-03T14:30:00Z",
      "event_name": "api_call",
      "properties": {
        "region": "us-west-2",
        "source": "API Gateway"
      },
      "idempotency_key": "unique-key-001"
    }
  ]
}

​
Step 5: Send the Event

  • In Postman, ensure your API call is set to POST and your request body is structured correctly with the above event format.
  • Adjust the timestamp to be within the grace period.
  • Orb allows a default grace period of 12 hours for late event reporting. If your timestamp exceeds this, update it to fit within that window.

​
Step 6: Check the Response

  • Once the event is accepted, Orb will return a success message.
  • You can enable debug mode to see details about the response, including any duplicates.
  • If you send the same event multiple times within the grace period, Orb will recognize it as a duplicate and ignore the second instance.
Troubleshooting Common Issues:
  • Grace Period Exceeded: If you attempt to send an event with a timestamp outside the grace period, adjust the timestamp to fit within the allowed window.
  • Duplicate Events: If you see a duplicate error in debug mode, the same event was sent twice within the grace period using the same idempotency key. Subsequent duplicate events in the grace period will be ignored.
By following these steps, you can successfully send your first usage event into Orb, experiment with test data, and see how your usage data is processed in the system.