{"info":{"title":"Hyperline Ingest API","version":"0.0.0"},"servers":[{"url":"https://ingest.hyperline.co"},{"url":"https://sandbox.ingest.hyperline.co"}],"openapi":"3.1.0","components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PaginatedEvent":{"type":"object","properties":{"meta":{"type":"object","properties":{"total":{"type":"number","description":"Total of existing items.","example":1},"taken":{"type":"number","description":"Number of items returned.","example":1},"skipped":{"type":"number","description":"Number of items skipped.","example":0}},"required":["total","taken","skipped"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Event ID in Hyperline.","example":"evt_abc123def456"},"event_type":{"type":"string","description":"Type of the event, as defined when ingesting events.","example":"api_call"},"timestamp":{"type":"string","description":"Timestamp of when the event occurred.","example":"2024-01-15T10:30:00.000Z"},"customer_id":{"type":["string","null"],"description":"ID of the customer associated with this event.","example":"cus_xyz789"},"record_id":{"type":"string","description":"External record ID provided when ingesting the event.","example":"rec_123"},"record":{"type":"object","additionalProperties":{},"description":"JSON payload of the event record.","example":{"id":"rec_123","endpoint":"/api/users","method":"GET"}}},"required":["id","event_type","timestamp","customer_id","record_id","record"]},"description":"List of Event."}},"required":["meta","data"]},"BillableEvent":{"type":"object","properties":{"customer_id":{"type":"string","description":"Hyperline ID or external ID of the existing customer.","example":"cus_CrqwefTRWBWRT"},"event_type":{"type":"string","minLength":1,"description":"Type corresponding to the event. When creating a dynamic product, this type will be used to map the related events to specific prices.","example":"api_call"},"timestamp":{"type":"string","format":"date-time","description":"UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, or milliseconds since the epoch. The event timestamp is used to retrieve the events related to a specific billing period.","example":"2024-12-20T16:04:11Z"},"record":{"allOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"A unique identifier for your event, used to identify the event in your system and prevent duplicates."}},"required":["id"]},{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]}}],"description":"Payload of the event containing an ID and any additional metadata.","example":{"id":"D32NAA8","durationInMs":32,"isVerified":true}}},"required":["customer_id","event_type","timestamp","record"]}},"parameters":{}},"paths":{"/v1/events":{"get":{"operationId":"getEvents","tags":["Billable events"],"security":[{"bearer":[]}],"summary":"Get events","description":"Retrieve billable events filtered by event type.","parameters":[{"schema":{"type":["number","null"],"minimum":0,"maximum":100,"default":50},"required":false,"name":"take","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0},"required":false,"name":"skip","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction.","example":"desc"},"required":false,"description":"Sort direction.","name":"order","in":"query"},{"schema":{"type":"string","enum":["timestamp"],"description":"Field used to sort the results."},"required":false,"description":"Field used to sort the results.","name":"sort","in":"query"},{"schema":{"type":"string","description":"Event type to filter by","example":"api_call"},"required":true,"description":"Event type to filter by","name":"event_type","in":"query"},{"schema":{"type":"string","description":"Filter by customer ID","example":"cus_xyz789"},"required":false,"description":"Filter by customer ID","name":"customer_id","in":"query"},{"schema":{"type":"string","description":"Filter by record ID. Supports comma-separated list for multiple records.","example":"rec_123"},"required":false,"description":"Filter by record ID. Supports comma-separated list for multiple records.","name":"record_id__in","in":"query"},{"schema":{"type":"object","additionalProperties":{"type":"string"},"description":"Filter on properties of the event record, passed as `record[<property>]=<value>` (for example `record[case_id]=cas_123`). Append `__in` to the property name to match a comma-separated list, such as `record[case_id__in]=cas_123,cas_456`. Values are compared as strings, several properties can be combined and are joined with a logical AND, and at most 5 properties can be filtered at once.","example":{"case_id":"cas_123"}},"required":false,"description":"Filter on properties of the event record, passed as `record[<property>]=<value>` (for example `record[case_id]=cas_123`). Append `__in` to the property name to match a comma-separated list, such as `record[case_id__in]=cas_123,cas_456`. Values are compared as strings, several properties can be combined and are joined with a logical AND, and at most 5 properties can be filtered at once.","name":"record","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter events with timestamp greater than or equal to this ISO8601 date.","example":"2024-01-01T00:00:00Z"},"required":false,"description":"Filter events with timestamp greater than or equal to this ISO8601 date.","name":"timestamp_gte","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Filter events with timestamp less than or equal to this ISO8601 date.","example":"2024-01-31T23:59:59Z"},"required":false,"description":"Filter events with timestamp less than or equal to this ISO8601 date.","name":"timestamp_lte","in":"query"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEvent"}}}}}},"post":{"operationId":"ingestBillableEvent","tags":["Billable events"],"security":[{"bearer":[]}],"summary":"Ingest billable event","description":"Ingest a new billable event. This endpoint is idempotent, an event with the same id will be updated if it already exists.","parameters":[{"schema":{"type":["boolean","null"],"description":"Whether to simulate prices for the event. Will be received in webhooks.","example":true},"required":false,"description":"Whether to simulate prices for the event. Will be received in webhooks.","name":"with_price_calculation","in":"query"}],"requestBody":{"description":"Event payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillableEvent"}}}},"responses":{"201":{"description":"Event ingested"}}},"delete":{"operationId":"deleteBillableEvents","tags":["Billable events"],"security":[{"bearer":[]}],"summary":"Delete billable events","description":"Delete existing billable events.","requestBody":{"description":"Delete billable events payload","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"matching":{"type":"string","enum":["record_ids"]},"record_ids":{"type":"array","items":{"type":"string"},"maxItems":5000,"description":"List of event record IDs to delete."}},"required":["matching","record_ids"]},{"type":"object","properties":{"matching":{"type":"string","enum":["customer_id"]},"customer_id":{"type":"string","description":"Customer ID for which the events will be deleted."},"event_type":{"type":"string","minLength":1,"description":"Type corresponding to the event. When creating a dynamic product, this type will be used to map the related events to specific prices.","example":"api_call"}},"required":["matching","customer_id"]},{"type":"object","properties":{"matching":{"type":"string","enum":["event_type"]},"event_type":{"type":"string","minLength":1,"description":"When matching by `event_type`, every event of this type will be deleted across all customers.","example":"api_call"}},"required":["matching","event_type"]},{"type":"object","properties":{"matching":{"type":"string","enum":["all"],"description":"All events will be deleted."}},"required":["matching"]}]}}}},"responses":{"200":{"description":"Events deleted","content":{"application/json":{"schema":{"type":"number","description":"Number of events deleted","example":1}}}}}}},"/v1/events/batch":{"post":{"operationId":"ingestBillableEvents","tags":["Billable events"],"security":[{"bearer":[]}],"summary":"Ingest billable events","description":"Ingest several billable events in batch (limited to max 5000 events per request). This endpoint is idempotent, an event with the same id, will be updated if it already exists.","requestBody":{"description":"Events payload","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BillableEvent"},"minItems":1,"maxItems":5000}}}},"responses":{"201":{"description":"Events ingested","content":{"application/json":{"schema":{"type":"object","properties":{"events_created":{"type":"array","items":{"$ref":"#/components/schemas/BillableEvent"}},"events_failed":{"type":"array","items":{"$ref":"#/components/schemas/BillableEvent"}}},"required":["events_created","events_failed"]}}}}}}},"/v1/events/simulate-prices":{"post":{"operationId":"simulateBillableEventPrices","tags":["Billable events"],"security":[{"bearer":[]}],"summary":"Simulate billable event prices","description":"Simulate prices for a single billable event without ingesting it.","parameters":[{"schema":{"type":"string","description":"Hyperline ID of the product.","example":"itm_AweveQEoewer"},"required":false,"description":"Hyperline ID of the product.","name":"product_id","in":"query"},{"schema":{"type":"string","description":"Hyperline ID of the subscription.","example":"sub_QalW2vTAdkR6IY"},"required":false,"description":"Hyperline ID of the subscription.","name":"subscription_id","in":"query"},{"schema":{"type":["boolean","null"],"description":"Whether to include amounts with tax","example":true},"required":false,"description":"Whether to include amounts with tax","name":"include_tax","in":"query"}],"requestBody":{"description":"Event payload","content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"type":"string","minLength":1,"description":"Type corresponding to the event. When creating a dynamic product, this type will be used to map the related events to specific prices.","example":"api_call"},"record":{"allOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"A unique identifier for your event, used to identify the event in your system and prevent duplicates."}},"required":["id"]},{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]}}],"description":"Payload of the event containing an ID and any additional metadata.","example":{"id":"D32NAA8","durationInMs":32,"isVerified":true}},"customer_id":{"type":"string","description":"Hyperline ID or external ID of the existing customer.","example":"cus_CrqwefTRWBWRT"},"timestamp":{"type":"string","format":"date-time","description":"UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, or milliseconds since the epoch. The event timestamp is used to retrieve the events related to a specific billing period.","example":"2024-12-20T16:04:11Z"}},"required":["event_type","record"]}}}},"responses":{"200":{"description":"Event prices simulated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID of the calculation.","example":"cal_1234567890"},"result":{"type":"array","items":{"allOf":[{"type":"object","properties":{"customer_id":{"type":["string","null"]},"subscription_id":{"type":["string","null"]}}},{"type":"object","properties":{"product_id":{"type":"string","description":"Hyperline ID of the product.","example":"itm_AweveQEoewer"},"price_group":{"type":"object","properties":{"id":{"type":"string","description":"ID of the group of tiers.","example":"grp_QalW2vTAdkR6IY"},"name":{"type":"string","description":"Name of the group of tiers.","example":"mastercard"}},"required":["id","name"]},"amount_excluding_tax":{"type":"number","description":"Amount excluding tax.","example":10000},"tax_amount":{"type":"number","description":"Tax estimate.","example":2000},"total_amount":{"type":"number","description":"Total amount. The final amount will be determined by the final invoice.","example":12000},"currency":{"type":"string","enum":["EUR","AED","AFN","XCD","ALL","AMD","AOA","ARS","USD","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","XOF","BMD","BND","BOB","BRL","BSD","BTN","NOK","BWP","BYR","BZD","CAD","CDF","XAF","CHF","NZD","CLP","CNY","COP","CRC","CUP","CVE","ANG","CZK","DJF","DKK","DOP","DZD","EGP","MAD","ERN","ETB","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MYR","MZN","NAD","XPF","NGN","NIO","NPR","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","UYU","UZS","VEF","VND","VUV","WST","YER","ZAR","ZMW","ZWL"],"description":"Currency code. See [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes).","example":"EUR"}},"required":["product_id","amount_excluding_tax","currency"]}]}}},"required":["id","result"]}}}}}}},"/v1/events/prices":{"get":{"operationId":"getBillableEventPrices","tags":["Billable events"],"security":[{"bearer":[]}],"summary":"Get billable event prices","description":"Get previous price simulation results for a billable event. You can search by either calculation_id / record_id or both.","parameters":[{"schema":{"type":"string","description":"A unique identifier for your event, used to identify the event in your system and prevent duplicates.","example":"D32NAA8"},"required":false,"description":"A unique identifier for your event, used to identify the event in your system and prevent duplicates.","name":"record_id","in":"query"},{"schema":{"type":"string","description":"ID of the calculation.","example":"cal_1234567890"},"required":false,"description":"ID of the calculation.","name":"calculation_id","in":"query"}],"responses":{"200":{"description":"Event prices previously calculated","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"ID of the calculation.","example":"cal_1234567890"},"result":{"type":"array","items":{"type":"object","properties":{"customer_id":{"type":"string","description":"Hyperline ID or external ID of the existing customer.","example":"cus_CrqwefTRWBWRT"},"event_timestamp":{"type":"string","format":"date-time","description":"UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, or milliseconds since the epoch. The event timestamp is used to retrieve the events related to a specific billing period.","example":"2024-12-20T16:04:11Z"},"subscription_id":{"type":"string"},"event_type":{"type":"string","minLength":1,"description":"Type corresponding to the event. When creating a dynamic product, this type will be used to map the related events to specific prices.","example":"api_call"},"product_id":{"type":"string","description":"Hyperline ID of the product.","example":"itm_AweveQEoewer"},"price_group":{"type":"object","properties":{"id":{"type":"string","description":"ID of the group of tiers.","example":"grp_QalW2vTAdkR6IY"},"name":{"type":"string","description":"Name of the group of tiers.","example":"mastercard"}},"required":["id","name"]},"record":{"allOf":[{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"A unique identifier for your event, used to identify the event in your system and prevent duplicates."}},"required":["id"]},{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"},{"type":"null"}]}}],"description":"Payload of the event containing an ID and any additional metadata.","example":{"id":"D32NAA8","durationInMs":32,"isVerified":true}},"amount_excluding_tax":{"type":"number","description":"Amount excluding tax.","example":10000},"tax_amount":{"type":"number","description":"Tax estimate.","example":2000},"total_amount":{"type":"number","description":"Total amount. The final amount will be determined by the final invoice.","example":12000},"currency":{"type":"string","enum":["EUR","AED","AFN","XCD","ALL","AMD","AOA","ARS","USD","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","XOF","BMD","BND","BOB","BRL","BSD","BTN","NOK","BWP","BYR","BZD","CAD","CDF","XAF","CHF","NZD","CLP","CNY","COP","CRC","CUP","CVE","ANG","CZK","DJF","DKK","DOP","DZD","EGP","MAD","ERN","ETB","FJD","FKP","GBP","GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","INR","IQD","IRR","ISK","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MDL","MGA","MKD","MMK","MNT","MOP","MRO","MUR","MVR","MWK","MXN","MYR","MZN","NAD","XPF","NGN","NIO","NPR","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SRD","SSP","STD","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TWD","TZS","UAH","UGX","UYU","UZS","VEF","VND","VUV","WST","YER","ZAR","ZMW","ZWL"],"description":"Currency code. See [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes).","example":"EUR"},"ingested":{"type":"boolean","description":"Whether the event has been ingested","example":true},"pre_calculated_at":{"type":"string","format":"date-time","description":"UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, or milliseconds since the epoch. The event timestamp is used to retrieve the events related to a specific billing period.","example":"2024-12-20T16:04:11Z"}},"required":["event_type","product_id","record","amount_excluding_tax","currency","ingested","pre_calculated_at"]}}},"required":["id","result"]}}}}}}}}},"webhooks":{}}