Usage

Ingest Event

Ingests a list of customer events, creating new events and identifying duplicates.

This endpoint processes a batch of customer events, checks for idempotency to prevent duplicates, and attempts to create new events in the system. It returns detailed information about the process, including the number of successfully created events, any duplicates identified, and errors encountered.

Parameters: request: The request object, which includes details about the HTTP request. This is typically provided by the FastAPI framework. customer_event_list (CustomerEventList): An object containing a list of customer events to be ingested. Each event must include an idempotency key to prevent duplicate processing.

Returns: A dictionary with two keys:

‘info’: A dictionary containing details about the ingestion process, including the number of events successfully created (‘created_events’) and a list of idempotency keys for events identified as duplicates (‘duplicates’).
‘errors’: A list of dictionaries, each representing an error encountered during the ingestion process. Each dictionary includes the ‘idempotency_key’ of the event that caused the error and a description of the error (‘error’).

POST

api

usage

ingest

curl --request POST \
  --url https://api.justpaid.io/api/v1/usage/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "events": []
}'

{
  "info": {
    "created_events": 5,
    "duplicates": []
  },
  "errors": []
}

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

object[]

Represents an event associated with a customer in the system.

Attributes: customer_id (Optional[Union[str, uuid.UUID]]): The unique identifier for the customer. This can be either a email or a UUID. event_name (str): The name of the event being recorded, it should be in snake_case format without spaces. for example: 'customer_created'. timestamp (str): The timestamp when the event occurred, in ISO 8601 format (e.g. 2024-08-09T00:00:00Z). idempotency_key (str): A unique string key to ensure idempotency of event processing. This key is used to identify duplicate events. item (Optional[uuid.UUID]): An optional billable item UUID that the event can be associated with. event_value (Union[float, int]): The value associated with the event. This can be either an integer or a float. external_customer_id (Optional[str]): An optional external identifier for the customer, provided as a string. properties (Optional[dict]): An optional dictionary containing additional properties or metadata associated with the event.

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 | 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

object | null

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

Example:

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

Response

200 - application/json

Detailed information about the customer event ingestion process.

Schema for the response of the customer event ingestion process.

Attributes: info (InfoSchema): Detailed information about the ingestion process, including the number of created events and duplicates. errors (list[ErrorSchema]): A list of errors that occurred during the ingestion process.

info

object

required

Detailed information about the customer event ingestion process.

info.created_events

integer

required

The number of events successfully created in the system from the input list of events provided to the endpoint.

Example:

5

info.duplicates

string[]

A list of idempotency keys for events identified as duplicates during the ingestion process.

Example:

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

errors

object[]

A list of errors that occurred during the ingestion process.

Represents an error that occurred during the ingestion process.

Attributes: idempotency_key (str): The idempotency key of the event that caused the error. error (str): A description of the error that occurred.

Invoice Payment Cancel Api Get Items

curl --request POST \
  --url https://api.justpaid.io/api/v1/usage/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "events": []
}'

{
  "info": {
    "created_events": 5,
    "duplicates": []
  },
  "errors": []
}

API Documentation

Authorizations

Body

Response