{ "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/PaginatedResponse_Customer" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] }, "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" }, "401": { "description": "Unauthorized" }, "404": { "description": "Customer not found" }, "409": { "description": "Customer already exists" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] } }, "/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" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] }, "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" }, "401": { "description": "Unauthorized" }, "404": { "description": "Customer not found" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] }, "delete": { "tags": [ "customer" ], "operationId": "delete_customer", "parameters": [ { "name": "id_or_alias", "in": "path", "description": "customer ID or alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer" }, "401": { "description": "Unauthorized" }, "404": { "description": "Customer not found" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] } }, "/api/v1/plans": { "get": { "tags": [ "plan" ], "operationId": "list_plans", "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": "product_family_id", "in": "query", "description": "Product family ID", "required": true, "schema": { "type": "string" }, "example": "default" }, { "name": "search", "in": "query", "description": "Filtering criteria", "required": true, "schema": { "type": "string" }, "example": "abc" } ], "responses": { "200": { "description": "List of plans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Plan" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] } }, "/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/PaginatedResponse_ProductFamily" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] }, "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": [ { "api-key": [] } ] } }, "/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": [ { "api-key": [] } ] } }, "/api/v1/subscriptions": { "get": { "tags": [ "subscription" ], "operationId": "list_subscriptions", "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 } ], "responses": { "200": { "description": "List of subscriptions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Subscription" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] } }, "/api/v1/subscriptions/{id}": { "get": { "tags": [ "subscription" ], "operationId": "subscription_details", "parameters": [ { "name": "id", "in": "path", "description": "subscription ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionDetails" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal error" } }, "security": [ { "api-key": [] } ] } }, "/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": { "Address": { "type": "object", "properties": { "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip_code": { "type": [ "string", "null" ] } } }, "BankAccountId": { "type": "string", "format": "MeteroidId", "examples": [ "ba_7n42DGM5Tflk9n8mt7Fhc7" ] }, "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" ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "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" } ] } } }, "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_vat_rate": { "type": [ "integer", "null" ], "format": "int32" }, "invoicing_emails": { "type": "array", "items": { "type": "string" } }, "invoicing_entity_id": { "oneOf": [ { "type": "null" }, { "$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" ] } } }, "CustomerId": { "type": "string", "format": "MeteroidId", "examples": [ "cus_7n42DGM5Tflk9n8mt7Fhc7" ] }, "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_vat_rate": { "type": [ "integer", "null" ], "format": "int32" }, "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" ] } } }, "InvoicingEntityId": { "type": "string", "format": "MeteroidId", "examples": [ "ive_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PaginatedResponse_Customer": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "invoicing_emails", "currency", "invoicing_entity_id" ], "properties": { "alias": { "type": [ "string", "null" ] }, "billing_address": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Address" } ] }, "billing_email": { "type": [ "string", "null" ] }, "currency": { "$ref": "#/components/schemas/Currency" }, "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" } ] } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_Plan": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "created_at", "plan_type", "status", "product_family_name", "product_family_id", "has_draft_version" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "has_draft_version": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/PlanId" }, "name": { "type": "string" }, "plan_type": { "$ref": "#/components/schemas/PlanTypeEnum" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" }, "product_family_name": { "type": "string" }, "status": { "$ref": "#/components/schemas/PlanStatusEnum" }, "subscription_count": { "type": [ "integer", "null" ], "format": "int64" } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_ProductFamily": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/ProductFamilyId" }, "name": { "type": "string" } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PaginatedResponse_Subscription": { "type": "object", "required": [ "data", "total" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "customer_id", "customer_name", "billing_day_anchor", "currency" ], "properties": { "billing_day_anchor": { "type": "integer", "format": "int32" }, "currency": { "type": "string" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "id": { "$ref": "#/components/schemas/SubscriptionId" } } } }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "Plan": { "type": "object", "required": [ "id", "name", "created_at", "plan_type", "status", "product_family_name", "product_family_id", "has_draft_version" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "has_draft_version": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/PlanId" }, "name": { "type": "string" }, "plan_type": { "$ref": "#/components/schemas/PlanTypeEnum" }, "product_family_id": { "$ref": "#/components/schemas/ProductFamilyId" }, "product_family_name": { "type": "string" }, "status": { "$ref": "#/components/schemas/PlanStatusEnum" }, "subscription_count": { "type": [ "integer", "null" ], "format": "int64" } } }, "PlanId": { "type": "string", "format": "MeteroidId", "examples": [ "plan_7n42DGM5Tflk9n8mt7Fhc7" ] }, "PlanStatusEnum": { "type": "string", "enum": [ "draft", "active", "inactive", "archived" ] }, "PlanTypeEnum": { "type": "string", "enum": [ "standard", "free", "custom" ] }, "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" ] }, "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" ], "properties": { "billing_day_anchor": { "type": "integer", "format": "int32" }, "currency": { "type": "string" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "id": { "$ref": "#/components/schemas/SubscriptionId" } } }, "SubscriptionDetails": { "type": "object", "required": [ "id", "customer_id", "customer_name", "billing_day_anchor", "currency" ], "properties": { "billing_day_anchor": { "type": "integer", "format": "int32" }, "currency": { "type": "string" }, "customer_alias": { "type": [ "string", "null" ] }, "customer_id": { "$ref": "#/components/schemas/CustomerId" }, "customer_name": { "type": "string" }, "id": { "$ref": "#/components/schemas/SubscriptionId" } } }, "SubscriptionId": { "type": "string", "format": "MeteroidId", "examples": [ "sub_7n42DGM5Tflk9n8mt7Fhc7" ] } }, "securitySchemes": { "api-key": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "tags": [ { "name": "meteroid", "description": "Meteroid API" } ] }