{ "openapi": "3.1.0", "info": { "title": "meteroid", "description": "", "license": { "name": "AGPL-3.0-only", "identifier": "AGPL-3.0-only" }, "version": "0.1.0" }, "paths": { "/api/v1/customers": { "get": { "tags": [ "customer" ], "operationId": "list_customers", "parameters": [ { "name": "offset", "in": "query", "description": "Specifies the starting position of the results", "required": true, "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "limit", "in": "query", "description": "The maximum number of objects to return", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "search", "in": "query", "description": "Filtering criteria", "required": true, "schema": { "type": "string" }, "example": "abc" } ], "responses": { "200": { "description": "List of customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "customer" ], "operationId": "create_customer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Customer successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "409": { "description": "Customer already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/customers/{id_or_alias}": { "get": { "tags": [ "customer" ], "operationId": "get_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "customer" ], "operationId": "update_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "customer" ], "operationId": "delete_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans": { "get": { "tags": [ "plan" ], "operationId": "list_plans", "parameters": [ { "name": "page", "in": "query", "description": "Specifies the starting position of the results", "required": true, "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "per_page", "in": "query", "description": "The maximum number of objects to return", "required": true, "schema": { "type": "integer", "maximum": 100, "minimum": 1 }, "example": 10 }, { "name": "product_family_id", "in": "query", "description": "Filter by a product family", "required": false, "schema": { "type": "string" }, "example": "default" } ], "responses": { "200": { "description": "List of plans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanListResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/plans/{plan_id}": { "get": { "tags": [ "plan" ], "operationId": "get_plan_details", "parameters": [ { "name": "plan_id", "in": "path", "description": "Plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "responses": { "200": { "description": "Plan details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Plan not found" }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/product_families": { "get": { "tags": [ "product_family" ], "operationId": "list_product_families", "parameters": [ { "name": "offset", "in": "query", "description": "Specifies the starting position of the results", "required": true, "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "limit", "in": "query", "description": "The maximum number of objects to return", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 10 }, { "name": "search", "in": "query", "description": "Filtering criteria", "required": true, "schema": { "type": "string" }, "example": "abc" } ], "responses": { "200": { "description": "List of product families", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamilyListResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "product_family" ], "operationId": "create_product_family", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamilyCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Customer successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamily" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/product_families/{id_or_alias}": { "get": { "tags": [ "product_family" ], "operationId": "get_product_family_by_id_or_alias", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "product_family ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "ProductFamily", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductFamily" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/subscriptions": { "get": { "tags": [ "subscription" ], "operationId": "list_subscriptions", "parameters": [ { "name": "page", "in": "query", "description": "Specifies the starting position of the results", "required": true, "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, { "name": "per_page", "in": "query", "description": "The maximum number of objects to return", "required": true, "schema": { "type": "integer", "maximum": 100, "minimum": 1 }, "example": 10 }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": true, "schema": { "$ref": "#/components/schemas/CustomerId" } }, { "name": "plan_id", "in": "query", "description": "Filter by plan ID", "required": true, "schema": { "$ref": "#/components/schemas/PlanId" } } ], "responses": { "200": { "description": "List of subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Subscription" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "subscription" ], "operationId": "create_subscription", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Subscription successfully created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/subscriptions/{id}": { "get": { "tags": [ "subscription" ], "operationId": "subscription_details", "parameters": [ { "name": "id", "in": "path", "description": "subscription ID", "required": true, "schema": { "$ref": "#/components/schemas/SubscriptionId" } } ], "responses": { "200": { "description": "Details of subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/files/v1/invoice/pdf/{uid}": { "get": { "tags": [ "file" ], "operationId": "get_invoice_pdf", "parameters": [ { "name": "uid", "in": "path", "description": "Invoice database UID", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "description": "Security token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invoice in PDF", "content": { "application/pdf": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "400": { "description": "Invalid UUID or token" }, "401": { "description": "Unauthorized - invalid token" }, "500": { "description": "Internal error" } } } }, "/files/v1/logo/{uuid}": { "get": { "tags": [ "file" ], "operationId": "get_logo", "parameters": [ { "name": "uuid", "in": "path", "description": "Logo database UUID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Logo as PNG image", "content": { "image/png": { "schema": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } } } } }, "400": { "description": "Invalid UUID" }, "500": { "description": "Internal error" } } } } }, "components": { "schemas": { "AddOnId": { "type": "string", "format": "MeteroidId", "examples": [ "add_7n42DGM5Tflk9n8mt7Fhc7" ] }, "Address": { "type": "object", "properties": { "city": { "type": [ "string", "null" ] }, "country": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CountryCode" } ] }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip_code": { "type": [ "string", "null" ] } } }, "AvailableParameters": { "type": "object", "properties": { "billing_periods": { "type": "object", "description": "Map of component_id -> available billing periods (e.g., \"MONTHLY\", \"ANNUAL\")", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/BillingPeriodEnum" } }, "propertyNames": { "type": "string" } }, "capacity_thresholds": { "type": "object", "description": "Map of component_id -> available capacity values", "additionalProperties": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "propertyNames": { "type": "string" } }, "slot_components": { "type": "array", "items": { "type": "string" }, "description": "List of component_ids that support slot parametrization (initial slot count)" } } }, "BankAccountId": { "type": "string", "format": "MeteroidId", "examples": [ "ba_7n42DGM5Tflk9n8mt7Fhc7" ] }, "BillableMetricId": { "type": "string", "format": "MeteroidId", "examples": [ "bm_7n42DGM5Tflk9n8mt7Fhc7" ] }, "BillingPeriodEnum": { "type": "string", "enum": [ "MONTHLY", "QUARTERLY", "ANNUAL" ] }, "BillingType": { "type": "string", "enum": [ "ADVANCE", "ARREARS" ] }, "BillingTypeEnum": { "type": "string", "enum": [ "ADVANCE", "ARREARS" ] }, "CapacityThreshold": { "type": "object", "required": [ "included_amount", "price", "per_unit_overage" ], "properties": { "included_amount": { "type": "integer", "format": "int64", "minimum": 0 }, "per_unit_overage": { "type": "number", "format": "double" }, "price": { "type": "number", "format": "double" } } }, "ComponentOverride": { "type": "object", "required": [ "component_id", "component" ], "properties": { "component": { "$ref": "#/components/schemas/SubscriptionComponent" }, "component_id": { "$ref": "#/components/schemas/PriceComponentId" } } }, "ComponentParameterization": { "type": "object", "required": [ "component_id", "parameters" ], "properties": { "component_id": { "$ref": "#/components/schemas/PriceComponentId" }, "parameters": { "$ref": "#/components/schemas/ComponentParameters" } } }, "ComponentParameters": { "type": "object", "properties": { "billing_period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingPeriodEnum" } ] }, "committed_capacity": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "initial_slot_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "CountryCode": { "type": "string", "format": "CountryCode", "examples": [ "US", "GB", "FR" ] }, "CreateSubscriptionAddOn": { "type": "object", "required": [ "add_on_id" ], "properties": { "add_on_id": { "$ref": "#/components/schemas/AddOnId" }, "customization": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SubscriptionAddOnCustomization" } ] } } }, "CreateSubscriptionComponents": { "type": "object", "properties": { "extra_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ExtraComponent" } }, "overridden_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ComponentOverride" } }, "parameterized_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ComponentParameterization" } }, "remove_components": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PriceComponentId" } } } }, "Currency": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNH", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "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", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "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", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL" ] }, "Customer": { "type": "object", "required": [ "id", "name", "invoicing_emails", "currency", "invoicing_entity_id" ], "properties": { "alias": { "type": [ "string", "null" ] }, "bank_account_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BankAccountId" } ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "custom_tax_rate": { "type": [ "number", "null" ], "format": "double" }, "id": { "$ref": "#/components/schemas/CustomerId" }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "invoicing_entity_id": { "$ref": "#/components/schemas/InvoicingEntityId" }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "shipping_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShippingAddress" } ] }, "vat_number": { "type": [ "string", "null" ] } } }, "CustomerCreateRequest": { "type": "object", "required": [ "name", "invoicing_emails", "currency" ], "properties": { "alias": { "type": [ "string", "null" ] }, "bank_account_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BankAccountId" } ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "custom_tax_rate": { "type": [ "number", "null" ], "format": "double" }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "invoicing_entity_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InvoicingEntityId" } ] }, "is_tax_exempt": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "shipping_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShippingAddress" } ] }, "vat_number": { "type": [ "string", "null" ] } } }, "CustomerId": { "type": "string", "format": "MeteroidId", "examples": [ "cus_7n42DGM5Tflk9n8mt7Fhc7" ] }, "CustomerListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "CustomerUpdateRequest": { "type": "object", "required": [ "name", "invoicing_emails", "currency", "invoicing_entity_id" ], "properties": { "alias": { "type": [ "string", "null" ] }, "bank_account_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BankAccountId" } ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "custom_tax_rate": { "type": [ "number", "null" ], "format": "double" }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "invoicing_entity_id": { "$ref": "#/components/schemas/InvoicingEntityId" }, "is_tax_exempt": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "shipping_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ShippingAddress" } ] }, "vat_number": { "type": [ "string", "null" ] } } }, "ErrorCode": { "type": "string", "enum": [ "BAD_REQUEST", "NOT_FOUND", "CONFLICT", "FORBIDDEN", "UNAUTHORIZED", "INTERNAL_SERVER_ERROR" ] }, "ExtraComponent": { "type": "object", "required": [ "component" ], "properties": { "component": { "$ref": "#/components/schemas/SubscriptionComponent" } } }, "Fee": { "oneOf": [ { "type": "object", "description": "Recurring rate fee (e.g., monthly subscription)", "required": [ "rates", "fee_type" ], "properties": { "fee_type": { "type": "string", "enum": [ "rate" ] }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/TermRate" } } } }, { "type": "object", "description": "Slot-based fee (e.g., per-seat pricing)", "required": [ "rates", "slot_unit_name", "fee_type" ], "properties": { "fee_type": { "type": "string", "enum": [ "slot" ] }, "minimum_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "quota": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/TermRate" } }, "slot_unit_name": { "type": "string" } } }, { "type": "object", "description": "Capacity-based fee with included committed usage and overage", "required": [ "metric_id", "thresholds", "fee_type" ], "properties": { "fee_type": { "type": "string", "enum": [ "capacity" ] }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "thresholds": { "type": "array", "items": { "$ref": "#/components/schemas/CapacityThreshold" } } } }, { "type": "object", "description": "Usage-based fee", "required": [ "metric_id", "pricing", "fee_type" ], "properties": { "fee_type": { "type": "string", "enum": [ "usage" ] }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "pricing": { "$ref": "#/components/schemas/UsagePricingModel" } } }, { "type": "object", "description": "Extra recurring fee", "required": [ "unit_price", "quantity", "billing_type", "cadence", "fee_type" ], "properties": { "billing_type": { "$ref": "#/components/schemas/BillingType" }, "cadence": { "$ref": "#/components/schemas/BillingPeriodEnum" }, "fee_type": { "type": "string", "enum": [ "extra_recurring" ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "unit_price": { "type": "number", "format": "double" } } }, { "type": "object", "description": "One-time fee", "required": [ "unit_price", "quantity", "fee_type" ], "properties": { "fee_type": { "type": "string", "enum": [ "one_time" ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "unit_price": { "type": "number", "format": "double" } } } ] }, "InvoicingEntityId": { "type": "string", "format": "MeteroidId", "examples": [ "ive_7n42DGM5Tflk9n8mt7Fhc7" ] }, "MatrixDimension": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } }, "MatrixRow": { "type": "object", "required": [ "dimension1", "per_unit_price" ], "properties": { "dimension1": { "$ref": "#/components/schemas/MatrixDimension" }, "dimension2": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MatrixDimension" } ] }, "per_unit_price": { "type": "string", "format": "decimal" } } }, "PaginatedResponse_Subscription": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "customer_id", "customer_name", "billing_day_anchor", "currency", "plan_id", "plan_name", "plan_version_id", "plan_version", "status", "current_period_start" ], "properties": { "billing_day_anchor": { "type": "integer", "format": "int32" }, "currency": { "$ref": "#/components/schemas/Currency" }, "current_period_end": { "type": [ "string", "null" ], "format": "date" }, "current_period_start": { "type": "string", "format": "date" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "id": { "$ref": "#/components/schemas/SubscriptionId" }, "plan_id": { "$ref": "#/components/schemas/PlanId" }, "plan_name": { "type": "string" }, "plan_version": { "type": "integer", "format": "int32", "minimum": 0 }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginationResponse": { "type": "object", "required": [ "page", "per_page", "total_items", "total_pages" ], "properties": { "page": { "type": "integer", "format": "int32", "minimum": 0 }, "per_page": { "type": "integer", "format": "int32", "minimum": 0 }, "total_items": { "type": "integer", "format": "int64", "minimum": 0 }, "total_pages": { "type": "integer", "format": "int32", "minimum": 0 } } }, "Plan": { "type": "object", "required": [ "id", "name", "created_at", "plan_type", "status", "product_family", "version_id", "version", "currency", "net_terms", "price_components", "available_parameters" ], "properties": { "available_parameters": { "$ref": "#/components/schemas/AvailableParameters" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/PlanId" }, "name": { "type": "string" }, "net_terms": { "type": "integer", "format": "int32" }, "plan_type": { "$ref": "#/components/schemas/PlanTypeEnum" }, "price_components": { "type": "array", "items": { "$ref": "#/components/schemas/PriceComponent" } }, "product_family": { "$ref": "#/components/schemas/ProductFamily" }, "status": { "$ref": "#/components/schemas/PlanStatusEnum" }, "trial": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TrialConfig" } ] }, "version": { "type": "integer", "format": "int32" }, "version_id": { "$ref": "#/components/schemas/PlanVersionId" } } }, "PlanId": { "type": "string", "format": "MeteroidId", "examples": [ "plan_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PlanListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "PlanStatusEnum": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "INACTIVE", "ARCHIVED" ] }, "PlanTypeEnum": { "type": "string", "enum": [ "STANDARD", "FREE", "CUSTOM" ] }, "PlanVersionId": { "type": "string", "format": "MeteroidId", "examples": [ "plv_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PriceComponent": { "type": "object", "required": [ "id", "name", "fee" ], "properties": { "fee": { "$ref": "#/components/schemas/Fee" }, "id": { "$ref": "#/components/schemas/PriceComponentId" }, "name": { "type": "string" }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] } } }, "PriceComponentId": { "type": "string", "format": "MeteroidId", "examples": [ "price_7n42DGM5Tflk9n8mt7Fhc7" ] }, "ProductFamily": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/ProductFamilyId" }, "name": { "type": "string" } } }, "ProductFamilyCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "ProductFamilyId": { "type": "string", "format": "MeteroidId", "examples": [ "pf_7n42DGM5Tflk9n8mt7Fhc7" ] }, "ProductFamilyListResponse": { "type": "object", "required": [ "data", "pagination_meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFamily" } }, "pagination_meta": { "$ref": "#/components/schemas/PaginationResponse" } } }, "ProductId": { "type": "string", "format": "MeteroidId", "examples": [ "prd_7n42DGM5Tflk9n8mt7Fhc7" ] }, "RestErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" } } }, "ShippingAddress": { "type": "object", "required": [ "same_as_billing" ], "properties": { "address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "same_as_billing": { "type": "boolean" } } }, "Subscription": { "type": "object", "required": [ "id", "customer_id", "customer_name", "billing_day_anchor", "currency", "plan_id", "plan_name", "plan_version_id", "plan_version", "status", "current_period_start" ], "properties": { "billing_day_anchor": { "type": "integer", "format": "int32" }, "currency": { "$ref": "#/components/schemas/Currency" }, "current_period_end": { "type": [ "string", "null" ], "format": "date" }, "current_period_start": { "type": "string", "format": "date" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "id": { "$ref": "#/components/schemas/SubscriptionId" }, "plan_id": { "$ref": "#/components/schemas/PlanId" }, "plan_name": { "type": "string" }, "plan_version": { "type": "integer", "format": "int32", "minimum": 0 }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" } } }, "SubscriptionActivationConditionEnum": { "type": "string", "enum": [ "ON_START", "ON_CHECKOUT", "MANUAL" ] }, "SubscriptionAddOnCustomization": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/SubscriptionAddOnOverride" }, { "type": "object", "required": [ "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "OVERRIDE" ] } } } ] }, { "allOf": [ { "$ref": "#/components/schemas/SubscriptionAddOnParameterization" }, { "type": "object", "required": [ "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "PARAMETERIZATION" ] } } } ] } ] }, "SubscriptionAddOnOverride": { "type": "object", "required": [ "name", "period", "fee" ], "properties": { "fee": { "$ref": "#/components/schemas/SubscriptionFee" }, "name": { "type": "string" }, "period": { "$ref": "#/components/schemas/SubscriptionFeeBillingPeriodEnum" } } }, "SubscriptionAddOnParameterization": { "type": "object", "properties": { "billing_period": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BillingPeriodEnum" } ] }, "committed_capacity": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "initial_slot_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "SubscriptionComponent": { "type": "object", "required": [ "name", "period", "fee", "is_override" ], "properties": { "fee": { "$ref": "#/components/schemas/SubscriptionFee" }, "is_override": { "type": "boolean" }, "name": { "type": "string" }, "period": { "$ref": "#/components/schemas/SubscriptionFeeBillingPeriodEnum" }, "price_component_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PriceComponentId" } ] }, "product_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ProductId" } ] } } }, "SubscriptionCreateRequest": { "type": "object", "required": [ "plan_version_id", "customer_id_or_alias", "start_date", "invoice_threshold", "activation_condition" ], "properties": { "activation_condition": { "$ref": "#/components/schemas/SubscriptionActivationConditionEnum" }, "add_ons": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CreateSubscriptionAddOn" } }, "billing_day_anchor": { "type": [ "integer", "null" ], "format": "int32", "maximum": 32767, "minimum": 1 }, "coupon_codes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "customer_id_or_alias": { "type": "string", "format": "CustomerId or customer alias" }, "end_date": { "type": [ "string", "null" ], "format": "date", "example": "2025-11-01" }, "invoice_memo": { "type": [ "string", "null" ] }, "invoice_threshold": { "type": "string", "format": "decimal" }, "net_terms": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "price_components": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateSubscriptionComponents" } ] }, "start_date": { "type": "string", "format": "date", "example": "2024-11-01" }, "trial_days": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "SubscriptionDetails": { "type": "object", "required": [ "id", "customer_id", "customer_name", "billing_day_anchor", "currency", "plan_id", "plan_name", "plan_version_id", "plan_version", "status", "current_period_start" ], "properties": { "billing_day_anchor": { "type": "integer", "format": "int32" }, "currency": { "$ref": "#/components/schemas/Currency" }, "current_period_end": { "type": [ "string", "null" ], "format": "date" }, "current_period_start": { "type": "string", "format": "date" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "id": { "$ref": "#/components/schemas/SubscriptionId" }, "plan_id": { "$ref": "#/components/schemas/PlanId" }, "plan_name": { "type": "string" }, "plan_version": { "type": "integer", "format": "int32", "minimum": 0 }, "plan_version_id": { "$ref": "#/components/schemas/PlanVersionId" }, "status": { "$ref": "#/components/schemas/SubscriptionStatusEnum" } } }, "SubscriptionFee": { "oneOf": [ { "type": "object", "required": [ "rate", "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "RATE" ] }, "rate": { "type": "string", "format": "decimal" } } }, { "type": "object", "required": [ "rate", "quantity", "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "ONE_TIME" ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "rate": { "type": "string", "format": "decimal" } } }, { "type": "object", "required": [ "rate", "quantity", "billing_type", "discriminator" ], "properties": { "billing_type": { "$ref": "#/components/schemas/BillingTypeEnum" }, "discriminator": { "type": "string", "enum": [ "RECURRING" ] }, "quantity": { "type": "integer", "format": "int32", "minimum": 0 }, "rate": { "type": "string", "format": "decimal" } } }, { "type": "object", "required": [ "rate", "included", "overage_rate", "metric_id", "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "CAPACITY" ] }, "included": { "type": "integer", "format": "int64", "minimum": 0 }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "overage_rate": { "type": "string", "format": "decimal" }, "rate": { "type": "string", "format": "decimal" } } }, { "type": "object", "required": [ "unit", "unit_rate", "initial_slots", "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "SLOT" ] }, "initial_slots": { "type": "integer", "format": "int32", "minimum": 0 }, "max_slots": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "min_slots": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "unit": { "type": "string" }, "unit_rate": { "type": "string", "format": "decimal" } } }, { "type": "object", "required": [ "metric_id", "model", "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "USAGE" ] }, "metric_id": { "$ref": "#/components/schemas/BillableMetricId" }, "model": { "$ref": "#/components/schemas/UsagePricingModel" } } } ] }, "SubscriptionFeeBillingPeriodEnum": { "type": "string", "enum": [ "ONE_TIME", "MONTHLY", "QUARTERLY", "ANNUAL" ] }, "SubscriptionId": { "type": "string", "format": "MeteroidId", "examples": [ "sub_7n42DGM5Tflk9n8mt7Fhc7" ] }, "SubscriptionStatusEnum": { "type": "string", "enum": [ "PENDING_ACTIVATION", "PENDING_CHARGE", "TRIAL_ACTIVE", "ACTIVE", "TRIAL_EXPIRED", "PAUSED", "SUSPENDED", "CANCELLED", "COMPLETED", "SUPERSEDED" ] }, "TermRate": { "type": "object", "required": [ "term", "price" ], "properties": { "price": { "type": "number", "format": "double" }, "term": { "$ref": "#/components/schemas/BillingPeriodEnum" } } }, "TierRow": { "type": "object", "required": [ "first_unit", "rate", "flat_fee", "flat_cap" ], "properties": { "first_unit": { "type": "integer", "format": "int64", "minimum": 0 }, "flat_cap": { "type": "string", "format": "decimal" }, "flat_fee": { "type": "string", "format": "decimal" }, "rate": { "type": "string", "format": "decimal" } } }, "TrialConfig": { "type": "object", "required": [ "duration_days", "is_free" ], "properties": { "duration_days": { "type": "integer", "format": "int32", "minimum": 0 }, "is_free": { "type": "boolean" }, "trialing_plan_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlanId" } ] } } }, "UsagePricingModel": { "oneOf": [ { "type": "object", "required": [ "rate", "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "PER_UNIT" ] }, "rate": { "type": "string", "format": "decimal" } } }, { "type": "object", "required": [ "tiers", "discriminator" ], "properties": { "block_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "discriminator": { "type": "string", "enum": [ "TIERED" ] }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/TierRow" } } } }, { "type": "object", "required": [ "tiers", "discriminator" ], "properties": { "block_size": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "discriminator": { "type": "string", "enum": [ "VOLUME" ] }, "tiers": { "type": "array", "items": { "$ref": "#/components/schemas/TierRow" } } } }, { "type": "object", "required": [ "block_size", "rate", "discriminator" ], "properties": { "block_size": { "type": "integer", "format": "int64", "minimum": 0 }, "discriminator": { "type": "string", "enum": [ "PACKAGE" ] }, "rate": { "type": "string", "format": "decimal" } } }, { "type": "object", "required": [ "rates", "discriminator" ], "properties": { "discriminator": { "type": "string", "enum": [ "MATRIX" ] }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/MatrixRow" } } } } ] } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } } }, "tags": [ { "name": "meteroid", "description": "Meteroid API" } ] }