Asynchronously Ingest Usage Data

curl --request POST \
  --url https://api.justpaid.io/api/v1/usage/ingest-async \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "event_name": "purchase_made",
      "timestamp": "2023-10-01T12:00:00Z",
      "idempotency_key": "unique-key-1",
      "event_value": 49.99,
      "properties": {
        "item_id": "A100",
        "quantity": 2
      }
    },
    {
      "customer_id": "123e4567-e89b-12d3-a456-426614174001",
      "event_name": "subscription_started",
      "timestamp": "2023-10-02T15:30:00Z",
      "idempotency_key": "unique-key-2",
      "event_value": 0,
      "properties": {
        "plan": "premium",
        "duration": "12_months"
      }
    }
  ]
}
'

{
  "job_id": "a4f8e9be-3d5b-4f8e-8b4d-9b4e5c9f5a2d",
  "status": "PENDING",
  "total_events": 2,
  "created_at": "2023-10-10T10:00:00Z"
}

POST

api

usage

ingest-async

Asynchronously Ingest Usage Data

curl --request POST \
  --url https://api.justpaid.io/api/v1/usage/ingest-async \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "events": [
    {
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "event_name": "purchase_made",
      "timestamp": "2023-10-01T12:00:00Z",
      "idempotency_key": "unique-key-1",
      "event_value": 49.99,
      "properties": {
        "item_id": "A100",
        "quantity": 2
      }
    },
    {
      "customer_id": "123e4567-e89b-12d3-a456-426614174001",
      "event_name": "subscription_started",
      "timestamp": "2023-10-02T15:30:00Z",
      "idempotency_key": "unique-key-2",
      "event_value": 0,
      "properties": {
        "plan": "premium",
        "duration": "12_months"
      }
    }
  ]
}
'

{
  "job_id": "a4f8e9be-3d5b-4f8e-8b4d-9b4e5c9f5a2d",
  "status": "PENDING",
  "total_events": 2,
  "created_at": "2023-10-10T10:00:00Z"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Represents a list of customer events.

Attributes: events (list[CustomerEvent]): A list of customer events. Each event should be a dictionary with at-least the following keys: event_name, timestamp, idempotency_key.

events

CustomerEvent · object[]

Show child attributes

events.event_name

string | null

required

The name of the event being recorded, this is used to map the event in the JustPaid. For example: 'customer_created' or 'invoice_parsed'.

Example:

"customer_created"

events.timestamp

string

required

The timestamp when the event occurred, in ISO 8601 format. the tiemstamp should be in UTC timezone.

Example:

"2024-08-09T00:00:00Z"

events.idempotency_key

string

required

A unique string key to ensure idempotency of event processing. This key is used to identify duplicate events. It's recommended to generate a new UUID for each event to prevent duplicates.

Example:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

events.customer_id

The unique identifier for the customer. This can be either an email or a UUID obtained from JustPaid Platform.

Example:

"123e4567-e89b-12d3-a456-426614174000"

events.item_id

string<uuid> | null

An optional UUID that the event can be associated with. If provided, this should be a UUID obtained from JustPaid Platform using api/v1/usage/events endpoint. and each item_id is associated with a plan_item in the system while creating the customer contract

Example:

"d3dc2e8f-2c78-4e3c-8b2c-649efdf5dd21"

events.event_value

The value associated with the event. This can be either an integer or a float, this value is used to calculate the billing amount for the customer provided that a billing metic is associated with the event.

Example:

100

events.external_customer_id

string | null

An optional external identifier for the customer, provided as a string. this used as an alias to JustPaid customer.

Example:

"external_12345"

events.properties

Properties · object

An optional dictionary containing additional properties or metadata associated with the event.

Example:

{ "property1": "value1", "property2": 5 }

Response

Successfully submitted the usage data for asynchronous processing.

job_id

string<uuid>

required

The UUID of the created batch job.

status

string

required

The status of the created batch job.

total_events

integer

required

The total number of events in the batch job.

created_at

string<date-time>

required

The timestamp when the batch job was created.

Ingest Event Retrieve Usage Data Batch Job Status

⌘I

API Documentation

Authorizations

Body

Response