Ingest Event

Ingest a raw metering event. The event is published to the meter-events PubSub topic for processing by the meters service.

POST /v0/events

Ingest Event

cURL

curl --request POST \
  --url https://api.paygentic.io/v0/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "source": "<string>",
  "subject": "<string>",
  "data": {},
  "externalSubject": "<string>",
  "namespace": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "idempotencyKey": "<string>",
  "externalId": "<string>"
}
'

import requests

url = "https://api.paygentic.io/v0/events"

payload = {
    "type": "<string>",
    "source": "<string>",
    "subject": "<string>",
    "data": {},
    "externalSubject": "<string>",
    "namespace": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "idempotencyKey": "<string>",
    "externalId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '<string>',
    source: '<string>',
    subject: '<string>',
    data: {},
    externalSubject: '<string>',
    namespace: '<string>',
    timestamp: '2023-11-07T05:31:56Z',
    idempotencyKey: '<string>',
    externalId: '<string>'
  })
};

fetch('https://api.paygentic.io/v0/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paygentic.io/v0/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => '<string>',
    'source' => '<string>',
    'subject' => '<string>',
    'data' => [
        
    ],
    'externalSubject' => '<string>',
    'namespace' => '<string>',
    'timestamp' => '2023-11-07T05:31:56Z',
    'idempotencyKey' => '<string>',
    'externalId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paygentic.io/v0/events"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"source\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"data\": {},\n  \"externalSubject\": \"<string>\",\n  \"namespace\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"idempotencyKey\": \"<string>\",\n  \"externalId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.paygentic.io/v0/events")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"source\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"data\": {},\n  \"externalSubject\": \"<string>\",\n  \"namespace\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"idempotencyKey\": \"<string>\",\n  \"externalId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paygentic.io/v0/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"<string>\",\n  \"source\": \"<string>\",\n  \"subject\": \"<string>\",\n  \"data\": {},\n  \"externalSubject\": \"<string>\",\n  \"namespace\": \"<string>\",\n  \"timestamp\": \"2023-11-07T05:31:56Z\",\n  \"idempotencyKey\": \"<string>\",\n  \"externalId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

202

{
  "id": "<string>",
  "object": "event",
  "type": "<string>",
  "source": "<string>",
  "subject": "<string>",
  "externalSubject": "<string>",
  "namespace": "<string>",
  "timestamp": "2023-11-07T05:31:56Z",
  "idempotencyKey": "<string>",
  "externalId": "<string>"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

Authorizations

Authorization · string · header · required

API key authentication

Body

application/json

Option 1

Option 2

type · string · required

CloudEvents type. Must match an eventType configured on a BillableMetric.

source · string · required

Event source URI identifying the application.

subject · string · required

Customer or entity ID this event relates to. Required unless externalSubject is provided.

data · object · required

Event payload containing the metering data.

externalSubject · string

Your own customer identifier, matched against the customer's externalId. Fallback for when the Paygentic customer ID is not known — prefer subject when it is. Events reported before the customer exists are linked retroactively once a customer with this externalId is created. Resolution is eventually consistent: after an externalId is removed or reassigned, events may resolve to the previous customer for up to one hour. If subject is also provided, subject takes precedence and externalSubject is recorded but not used for resolution.

Maximum string length: 255

Pattern: ^[a-zA-Z0-9_-]+$

namespace · string

Organization/merchant ID. Defaults to the authenticated user's organization. Platform users can specify a different organization.

timestamp · string<date-time>

Event timestamp. Defaults to server time if not provided.

idempotencyKey · string

User-provided deduplication key. If not provided, a unique key is generated.

externalId · string

Optional external identifier for cross-referencing with external systems. Alphanumeric characters, hyphens, and underscores only.

Maximum string length: 255

Pattern: ^[a-zA-Z0-9_-]+$

Response

202

application/json

Event accepted for processing

id · string

Server-generated event ID.

object · enum<string> · default: event

Available options: event

type · string

source · string

subject · string

Resolved customer ID. Absent when the event was reported with an externalSubject that does not match a customer yet.

externalSubject · string

The merchant's own customer identifier the event was reported with.

namespace · string

timestamp · string<date-time>

idempotencyKey · string

externalId · string

Optional external identifier for cross-referencing with external systems. Alphanumeric characters, hyphens, and underscores only.

Maximum string length: 255

Pattern: ^[a-zA-Z0-9_-]+$