{ "openapi": "3.1.0", "info": { "title": "Plock external API", "version": "0.2.1" }, "servers": [ { "url": "https://api.plock.io", "description": "Production" }, { "url": "https://test-api.plock.io", "description": "Test" } ], "paths": { "/api/c1/accounts": { "get": { "tags": [ "Accounts" ], "summary": "Get all accounts", "operationId": "getAccounts", "parameters": [ { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } }, { "name": "filter", "in": "query", "description": "Filter to use", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "parentAccountId": { "description": "Get all accounts where parent account ID is ..", "type": "integer", "example": 15 }, "primaryKey": { "description": "Get all accounts where primary key is ..", "type": "string", "example": "a123" }, "active": { "description": "Get only active accounts", "type": "boolean", "example": true }, "archived": { "description": "Get only archived accounts", "type": "boolean", "example": true }, "pending": { "description": "Get only pending accounts", "type": "boolean", "example": true } }, "type": "object" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "meta": { "$ref": "#/components/schemas/JsonApiMeta" }, "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Accounts" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/accounts/{accountId}": { "get": { "tags": [ "Accounts" ], "summary": "Get specific account", "operationId": "getAccountById", "parameters": [ { "name": "accountId", "in": "path", "description": "Plock account ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" }, "data": { "$ref": "#/components/schemas/Accounts" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "Get all subscriptions", "operationId": "getSubscriptions", "parameters": [ { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "meta": { "$ref": "#/components/schemas/JsonApiMeta" }, "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscriptions" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/subscriptions/{subscriptionId}": { "get": { "tags": [ "Subscriptions" ], "summary": "Get specific subscription", "operationId": "getSubscriptionById", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Plock subscription ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" }, "data": { "$ref": "#/components/schemas/Subscriptions" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/subscriptions/{subscriptionId}/subscription-items": { "get": { "tags": [ "Subscriptions" ], "summary": "Get items for a specific subscription", "operationId": "getSubscriptionItemsBySubscriptionId", "parameters": [ { "name": "subscriptionId", "in": "path", "description": "Plock subscription ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItems" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/invoices": { "get": { "tags": [ "Invoices" ], "summary": "Get all invoices", "operationId": "getInvoices", "parameters": [ { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } }, { "name": "filter", "in": "query", "description": "Filter to use", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "parentInvoiceId": { "description": "Get all invoices where parent invoice ID is ..", "type": "integer", "example": 15 }, "accountId": { "description": "Get all invoices where the account ID is ..", "type": "integer", "example": 12 }, "subscriptionId": { "description": "Get all invoices where the subscription ID is ..", "type": "integer", "example": 10 } }, "type": "object" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "meta": { "$ref": "#/components/schemas/JsonApiMeta" }, "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoices" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/invoices/{invoiceId}": { "get": { "tags": [ "Invoices" ], "summary": "Get specific invoice", "operationId": "getInvoiceById", "parameters": [ { "name": "invoiceId", "in": "path", "description": "Plock invoice ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" }, "data": { "$ref": "#/components/schemas/Invoices" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/invoices/{invoiceId}/invoice-items": { "get": { "tags": [ "Invoices" ], "summary": "Get items for a specific invoice", "operationId": "getInvoiceItemsByInvoiceId", "parameters": [ { "name": "invoiceId", "in": "path", "description": "Plock invoice ID", "required": true, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceItems" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } }, "/api/c1/product-usages": { "get": { "tags": [ "Usage" ], "summary": "Get all product usage", "operationId": "getProductUsages", "parameters": [ { "name": "page", "in": "query", "description": "Pagination number and size", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "size": { "description": "Number of objects returned per page", "type": "integer", "example": 15 }, "number": { "description": "Page number", "type": "integer", "example": 5 } }, "type": "object" } }, { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/vnd.api+json" ] } }, { "name": "filter", "in": "query", "description": "Filter to use", "required": false, "style": "deepObject", "explode": true, "schema": { "properties": { "accountId": { "description": "Get all usage where account ID is ..", "type": "integer", "example": 15 }, "productId": { "description": "Get all usage where product ID is ..", "type": "integer", "example": 12 }, "timestampBetween": { "description": "Get all usage where timestamp is between \"X,Y\"", "type": "string", "format": "date", "example": "2025-04-22T00:00:00.000000Z,2025-03-10T00:00:00.000000Z" } }, "type": "object" } } ], "responses": { "200": { "description": "OK", "content": { "application/vnd.api+json": { "schema": { "properties": { "meta": { "$ref": "#/components/schemas/JsonApiMeta" }, "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "links": { "$ref": "#/components/schemas/JsonApiLinks" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductUsages" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/vnd.api+json": { "schema": { "properties": { "jsonapi": { "$ref": "#/components/schemas/JsonApiVersion" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/JsonApiErrors" } } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Usage" ], "summary": "Add product usage", "operationId": "addProductUsages", "parameters": [ { "name": "Accept", "in": "header", "description": "The client must specify an Accept header.", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "Content-Type", "in": "header", "description": "The client must specify a Content-Type header.", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "Product usage", "required": true, "content": { "application/json": { "schema": { "properties": { "ts": { "description": "UNIX timestamp of value", "type": "integer", "example": 1756582856 }, "value": { "description": "Value recorded at ts", "type": "number", "format": "float", "example": 10.5 }, "crm_id": { "description": "CRM ID of the account", "type": "string", "example": "xx123" }, "product_id": { "description": "Product ID for the product", "type": "integer", "example": 332 } }, "type": "object" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "unauthorized" } }, "type": "object" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The crm_id does not exist." }, "errors": { "type": "array", "items": {} } }, "type": "object" } } } }, "422": { "description": "Unprocessable content", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "The crm id field must be a string." }, "errors": { "type": "array", "items": {} } }, "type": "object" } } } } }, "security": [ { "bearer": [] } ] } } }, "components": { "schemas": { "AccountsRelationships": { "properties": { "subscriptions": { "type": "string" }, "invoices": { "type": "string" } }, "type": "object" }, "Accounts": { "properties": { "type": { "type": "string", "example": "accounts" }, "id": { "type": "string", "example": "2002" }, "attributes": { "properties": { "primaryKey": { "title": "primaryKey", "description": "Your accounts primary ID", "type": "string", "example": "a443322" }, "name": { "title": "name", "description": "Account name", "type": "string", "example": "Some Company AB" }, "orgNumber": { "title": "orgNumber", "description": "Organisation number", "type": [ "string", "null" ], "example": "554433-3344" }, "crmId": { "title": "crmId", "description": "External CRM ID, for example from Hubspot", "type": [ "string", "null" ], "example": "hs321" }, "erpId": { "title": "erpId", "description": "External ERP ID, for example from Fortnox", "type": [ "string", "null" ], "example": "fn432" }, "country": { "title": "country", "description": "Primary country this account belongs to", "type": [ "string", "null" ], "example": "Sweden" }, "parentAccountId": { "title": "parentAccountId", "description": "Account ID (parent) that this account belongs to", "type": [ "integer", "null" ], "example": 1 }, "createdAt": { "title": "createdAt", "type": "string", "format": "date-time" }, "updatedAt": { "title": "updatedAt", "type": "string", "format": "date-time" }, "isGroup": { "title": "isGroup", "description": "Is this a group account?", "type": "boolean" }, "belongsToGroup": { "title": "belongsToGroup", "description": "Does this account belong to a group account?", "type": "boolean" }, "isArchived": { "title": "isArchived", "description": "Has this account been archived?", "type": "boolean" }, "isActive": { "title": "isActive", "description": "Is this account active?", "type": "boolean" }, "isPending": { "title": "isPending", "description": "Is this account pending creation?", "type": "boolean" }, "stats": { "$ref": "#/components/schemas/AccountStats", "description": "Account financial statistics, these will be variable length arrays where each item represents the value at a month and the last item of the array represents the value at the previous month (now -1 month)" } }, "type": "object" }, "relationships": { "$ref": "#/components/schemas/AccountsRelationships" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" } }, "type": "object" }, "AccountStats": { "properties": { "mrr_committed_fees": { "type": "array", "items": { "type": "number" }, "example": [ 100.5, 200.3, 300.2 ] }, "mrr_usage_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 0 ] }, "mrr_one_time_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 200 ] }, "billings_committed_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 601 ] }, "billings_usage_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 0 ] }, "billings_one_time_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 200 ] } }, "type": "object" }, "InvoiceItemsRelationships": { "properties": { "invoices": { "type": "string" } }, "type": "object" }, "InvoiceItems": { "properties": { "type": { "type": "string", "example": "invoice-items" }, "id": { "type": "string", "example": "3001" }, "attributes": { "properties": { "unit_amount": { "title": "unit_amount", "description": "Price per unit (null for tiered plans)", "type": [ "number", "null" ], "example": 10 }, "quantity": { "title": "quantity", "description": "Quantity of units ", "type": "number", "example": 100 }, "amount": { "title": "amount", "description": "Total amount for the line item (excluding any rebate)", "type": [ "number", "null" ], "example": 1104.45 }, "rebate": { "title": "rebate", "description": "Total rebate for the line item", "type": [ "number", "null" ], "example": -10.45 }, "breakdown": { "title": "breakdown", "description": "Detailed breakdown of charges", "type": [ "object", "null" ], "example": { "rebate": -10.45 } }, "product_name": { "title": "product_name", "description": "Name of the product", "type": [ "string", "null" ], "example": "API Calls" }, "plan_name": { "title": "plan_name", "description": "Name of the plan", "type": [ "string", "null" ], "example": "Bronze plan" }, "description": { "title": "description", "description": "Description of the invoice item", "type": [ "string", "null" ], "example": "A description text" }, "type": { "title": "type", "description": "Type of invoice item", "type": "string", "example": "Revenue" } }, "type": "object" }, "relationships": { "$ref": "#/components/schemas/InvoiceItemsRelationships" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" } }, "type": "object" }, "InvoicesRelationships": { "properties": { "subscriptions": { "type": "string" }, "accounts": { "type": "string" }, "invoice-items": { "type": "string" } }, "type": "object" }, "Invoices": { "properties": { "type": { "type": "string", "example": "invoices" }, "id": { "type": "string", "example": "2002" }, "attributes": { "properties": { "amount": { "title": "amount", "description": "Amount for the invoice", "type": "number", "example": "1000.00" }, "accountId": { "title": "accountId", "description": "Account ID", "type": "integer", "example": "5001" }, "erpId": { "title": "erpId", "description": "External ERP ID, for example from Fortnox", "type": [ "string", "null" ], "example": "fn123" }, "subscriptionId": { "title": "subscriptionId", "description": "Subscription ID", "type": "integer", "example": "4342" }, "currency": { "title": "currency", "description": "Currency of the invoice", "type": "string", "example": "EUR" }, "invoiceType": { "title": "invoiceType", "description": "Type of invoice", "type": "string", "example": "In arrears" }, "periodStart": { "title": "periodStart", "description": "Start of the period for the invoice", "type": "string", "format": "date" }, "periodEnd": { "title": "periodEnd", "description": "End of the period for the invoice", "type": "string", "format": "date" }, "createdAt": { "title": "createdAt", "type": "string", "format": "date-time" }, "updatedAt": { "title": "updatedAt", "type": "string", "format": "date-time" }, "dueAt": { "title": "dueAt", "description": "Invoice due at (from ERP)", "type": "string", "format": "date-time" }, "paymentStatus": { "title": "paymentStatus", "description": "Payment status (from ERP)", "type": "string", "example": "Paid" }, "parentInvoiceId": { "title": "parentInvoiceId", "description": "Invoice ID (parent) that this invoice belongs to", "type": [ "integer", "null" ], "example": 1001 }, "isParent": { "title": "isParent", "description": "Is this the parent invoice?", "type": "boolean", "example": false } }, "type": "object" }, "relationships": { "$ref": "#/components/schemas/InvoicesRelationships" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" } }, "type": "object" }, "ProductUsages": { "properties": { "type": { "type": "string", "example": "product-usage" }, "id": { "type": "string", "example": "2002" }, "attributes": { "properties": { "accountId": { "title": "accountId", "description": "The account ID in Plock", "type": "number", "example": 13321 }, "crmId": { "title": "crmId", "description": "Your accounts CRM ID", "type": "string", "example": "a341324" }, "productId": { "title": "productId", "description": "The product ID in Plock", "type": "string", "example": 41231 }, "value": { "title": "value", "description": "The value recorded", "type": "number", "example": 1.0576 }, "timestamp": { "title": "timestamp", "description": "The timestamp recorded", "type": "string", "format": "date", "example": "2025-05-30T00:00:00.000000Z" }, "description": { "title": "description", "description": "Optional free-text description", "type": "string", "example": "March SMS batch" } }, "type": "object" }, "relationships": { "properties": {} }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" } }, "type": "object" }, "JsonApiMeta": { "properties": { "page": { "properties": { "currentPage": { "type": "integer" }, "from": { "type": "integer" }, "lastPage": { "type": "integer" }, "perPage": { "type": "integer" }, "to": { "type": "integer" }, "total": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "JsonApiVersion": { "properties": { "version": { "type": "string", "example": "1.0" } }, "type": "object" }, "JsonApiLinks": { "properties": { "first": { "type": "string" }, "last": { "type": "string" }, "next": { "type": "string" } }, "type": "object" }, "JsonApiLinksSingle": { "properties": { "self": { "type": "string" } }, "type": "object" }, "JsonApiErrors": { "properties": { "detail": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "SubscriptionItemsRelationships": { "properties": { "subscriptions": { "description": "Note: There is no direct resource route for subscription-items.\nItems are only served as a subscription relationship, via\nSubscriptionController::showRelatedSubscriptionItems() which\nuses getItemsAtDate() to resolve scheduled changes correctly.", "type": "string" } }, "type": "object" }, "SubscriptionItems": { "properties": { "type": { "type": "string", "example": "subscription-items" }, "id": { "type": "string", "example": "2002" }, "attributes": { "properties": { "subscriptionId": { "title": "subscriptionId", "description": "ID of the subscription that the subscription item belongs to", "type": "string", "example": "1001" }, "planName": { "title": "planName", "description": "Name of the price plan", "type": "string", "example": "Annual price" }, "productName": { "title": "productName", "description": "Name of the product", "type": "string", "example": "Send SMS" }, "quantity": { "title": "quantity", "description": "Quantity added", "type": [ "integer", "null" ], "example": 100 }, "rebateAmount": { "title": "rebateAmount", "description": "Rebate amount", "type": [ "integer", "null" ], "example": 10 }, "rebateType": { "title": "rebateType", "description": "Rebate type", "type": [ "string", "null" ], "example": "percent" }, "description": { "title": "description", "description": "Description of the subscription item", "type": [ "string", "null" ], "example": "Custom line item description" }, "costCenter": { "title": "costCenter", "description": "Cost center for the subscription item", "type": [ "string", "null" ], "example": "CC-001" }, "project": { "title": "project", "description": "Project for the subscription item", "type": [ "string", "null" ], "example": "Project Alpha" }, "contractedUsage": { "title": "contractedUsage", "description": "Contracted usage as defined by the first tier of the price plan", "type": [ "number", "null" ], "format": "float", "example": 1000 }, "createdAt": { "title": "createdAt", "type": "string", "format": "date-time" }, "updatedAt": { "title": "updatedAt", "type": "string", "format": "date-time" } }, "type": "object" }, "relationships": { "$ref": "#/components/schemas/SubscriptionItemsRelationships" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" } }, "type": "object" }, "SubscriptionsRelationships": { "properties": { "accounts": { "type": "string" }, "invoices": { "type": "string" }, "subscription-items": { "type": "string" } }, "type": "object" }, "Subscriptions": { "properties": { "type": { "type": "string", "example": "subscriptions" }, "id": { "type": "string", "example": "2002" }, "attributes": { "properties": { "accountId": { "title": "Account ID", "description": "Account ID", "type": "string", "example": "2002" }, "crmDealId": { "title": "CRM Deal ID", "description": "CRM Deal ID", "type": "string", "example": "40048111" }, "name": { "title": "name", "description": "Name of the subscription", "type": "string", "example": "My annual subscription" }, "billingInterval": { "title": "billingInterval", "description": "Billing interval", "type": "string", "example": "month" }, "billingIntervalName": { "title": "billingIntervalName", "description": "Billing interval name", "type": "string", "example": "Monthly in arrears" }, "billingPractice": { "title": "billingPractice", "description": "Billing practice", "type": "string", "example": "in_arrears" }, "state": { "title": "state", "description": "State of this subscription", "type": "string", "example": "Ended" }, "billingIntervalCount": { "title": "billingIntervalCount", "description": "Interval counter", "type": "integer", "example": 12 }, "isActive": { "title": "isActive", "description": "Is this subscription active?", "type": "boolean" }, "billingCycleAnchor": { "title": "billingCycleAnchor", "description": "Anchor date / start date for subscription", "type": "string", "format": "date-time" }, "renewalDate": { "title": "renewalDate", "description": "Renewal date for this subscription", "type": [ "string", "null" ], "format": "date-time", "example": "2025-06-30" }, "renewalTerm": { "title": "renewalTerm", "description": "Renewal term (in months)", "type": [ "integer", "null" ], "example": 12 }, "cancelEndDate": { "title": "cancelEndDate", "description": "End date to cancel this subscription", "type": [ "string", "null" ], "format": "date-time", "example": "2025-05-30" }, "cancelPeriod": { "title": "cancelPeriod", "description": "Cancellation period (in months)", "type": "integer", "example": 3 }, "rebateEndDate": { "title": "rebateEndDate", "description": "End date for rebate", "type": [ "string", "null" ], "format": "date-time", "example": "2024-07-01" }, "rebateAmount": { "title": "rebateAmount", "description": "Rebate amount", "type": [ "integer", "null" ], "example": 2000 }, "rebateType": { "title": "rebateType", "description": "Rebate type", "type": [ "string", "null" ], "example": "percent" }, "currency": { "title": "currency", "description": "Currency", "type": "string", "example": "SEK" }, "minimumCommitment": { "title": "minimumCommitment", "description": "Minimum commitment", "type": [ "integer", "null" ], "example": 2000 }, "currentBillingPeriod": { "title": "currentBillingPeriod", "description": "Current active billing period", "type": "string", "example": "2024-03-01 - 2024-03-31" }, "autoSendToAccounting": { "title": "autoSendToAccounting", "description": "Automatically send invoices for this subscription", "type": "boolean" }, "endDate": { "title": "endDate", "description": "End date for subscription", "type": [ "string", "null" ], "format": "date-time", "example": "2024-07-01" }, "signedAt": { "title": "signedAt", "description": "Date when the subscription was signed/contracted", "type": [ "string", "null" ], "format": "date-time", "example": "2024-01-15" }, "endDateNoticedAt": { "title": "endDateNoticedAt", "description": "Date when end/cancellation was noticed", "type": [ "string", "null" ], "format": "date-time", "example": "2024-06-01" }, "metaData": { "title": "metaData", "description": "Free-form metadata for the subscription", "type": [ "object", "null" ] }, "createdAt": { "title": "createdAt", "type": "string", "format": "date-time" }, "updatedAt": { "title": "updatedAt", "type": "string", "format": "date-time" }, "nextIndexationDate": { "title": "nextIndexationDate", "description": "Next indexation date for subscription", "type": [ "string", "null" ], "format": "date-time", "example": "2026-01-01" }, "indexationPercentage": { "title": "indexationPercentage", "description": "Indexation percentage that will be applied on nextIndexationDate", "type": [ "number", "null" ], "example": "4.5" }, "stats": { "$ref": "#/components/schemas/SubscriptionStats", "description": "Subscription financial statistics, these will be variable length arrays where each item represents the value at a month and the last item of the array represents the value at the previous month (now -1 month)" } }, "type": "object" }, "relationships": { "$ref": "#/components/schemas/SubscriptionsRelationships" }, "links": { "$ref": "#/components/schemas/JsonApiLinksSingle" } }, "type": "object" }, "SubscriptionStats": { "properties": { "mrr_committed_fees": { "type": "array", "items": { "type": "number" }, "example": [ 100.5, 200.3, 300.2 ] }, "mrr_usage_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 0 ] }, "mrr_one_time_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 200 ] }, "billings_committed_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 601 ] }, "billings_usage_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 0 ] }, "billings_one_time_fees": { "type": "array", "items": { "type": "number" }, "example": [ 0, 0, 200 ] } }, "type": "object" } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "tags": [ { "name": "Accounts", "description": "Accounts" }, { "name": "Subscriptions", "description": "Subscriptions" }, { "name": "Invoices", "description": "Invoices" }, { "name": "Usage", "description": "Usage" } ] }