diff --git a/openapi.yaml b/openapi.yaml index 15854d7..2de3c1f 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2230,6 +2230,60 @@ paths: $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/NotAllowed' + '/subscriptions/{external_id}/lifetime_usage': + parameters: + - name: external_id + in: path + description: External ID of the existing subscription + required: true + schema: + type: string + example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba + get: + tags: + - subscriptions + summary: Retrive subscription lifetime usage + description: This endpoint enables the retrieval of the lifetime usage of a subscription. + operationId: getSubscriptionLifetimeUsage + responses: + '200': + description: Subscription lifetime usage + content: + application/json: + schema: + $ref: '#/components/schemas/LifetimeUsage' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + put: + tags: + - subscriptions + summary: Update a subscription lifetime usage + description: This endpoint allows you to update the lifetime usage of a subscription. + operationId: updateSubscriptionLifetimeUsage + requestBody: + description: Update the lifetime usage of a subscription + content: + application/json: + schema: + $ref: '#/components/schemas/LifetimeUsageInput' + required: true + responses: + '200': + description: Subscription lifetime usage updated + content: + application/json: + schema: + $ref: '#/components/schemas/LifetimeUsage' + '400': + $ref: '#/components/responses/BadRequest' + '401': + $ref: '#/components/responses/Unauthorized' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' /taxes: post: tags: @@ -6405,6 +6459,101 @@ components: type: array items: $ref: '#/components/schemas/GrossRevenueObject' + LifetimeUsage: + type: object + required: + - lifetime_usage + properties: + lifetime_usage: + $ref: '#/components/schemas/LifetimeUsageObject' + LifetimeUsageInput: + type: object + required: + - lifetime_usage + properties: + lifetime_usage: + type: object + required: + - external_historical_usage_amount_cents + properties: + external_historical_usage_amount_cents: + type: integer + example: 100 + description: The historical usage amount in cents for the subscription (provided by your own application). + LifetimeUsageObject: + type: object + required: + - lago_id + - lago_subscription_id + - external_subscription_id + - external_historical_usage_amount_cents + - invoiced_usage_amount_cents + - current_usage_amount_cents + - from_datetime + - to_datetime + properties: + lago_id: + type: string + format: uuid + example: 1a901a90-1a90-1a90-1a90-1a901a901a90 + description: Unique identifier assigned to the lifetime usage record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the lifetime usage record within the Lago system + lago_subscription_id: + type: string + format: uuid + example: 1a901a90-1a90-1a90-1a90-1a901a901a90 + description: Unique identifier assigned to the subscription record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription record within the Lago system + external_subscription_id: + type: string + example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba + description: The subscription external unique identifier (provided by your own application). + external_historical_usage_amount_cents: + type: integer + example: 100 + description: The historical usage amount in cents for the subscription (provided by your own application). + invoiced_usage_amount_cents: + type: integer + example: 100 + description: The total invoiced usage amount in cents for the subscription. + current_usage_amount_cents: + type: integer + example: 100 + description: The current usage amount in cents for the subscription on the current billing period. + from_datetime: + type: string + format: date-time + example: '2024-01-01T00:00:00Z' + description: The recording start date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format. + to_datetime: + type: string + format: date-time + example: '2024-12-31T23:59:59Z' + description: The recording end date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format. + usage_thresholds: + type: array + description: Array of usage thresholds attached to the subscription's plan. + items: + $ref: '#/components/schemas/LifetimeUsageThresholdObject' + LifetimeUsageThresholdObject: + type: object + required: + - amount_cents + - completion_ratio + - reached_at + properties: + amount_cents: + type: integer + description: The usage threshold amount in cents. + example: 100 + completion_ratio: + type: number + description: The completion ratio of the usage threshold. + example: 0.5 + reached_at: + type: string + format: date-time + description: The date and time when the usage threshold was reached. The date and time must be in ISO 8601 format. + example: '2024-01-01T00:00:00Z' + nullable: true MinimumCommitmentInput: type: object description: Minimum commitment for this plan. diff --git a/src/openapi.yaml b/src/openapi.yaml index 1037d94..27bd930 100644 --- a/src/openapi.yaml +++ b/src/openapi.yaml @@ -198,6 +198,8 @@ paths: $ref: "./resources/subscriptions.yaml" /subscriptions/{external_id}: $ref: "./resources/subscription.yaml" + /subscriptions/{external_id}/lifetime_usage: + $ref: "./resources/subscription_lifetime_usage.yaml" /taxes: $ref: "./resources/taxes.yaml" /taxes/{code}: diff --git a/src/resources/subscription_lifetime_usage.yaml b/src/resources/subscription_lifetime_usage.yaml new file mode 100644 index 0000000..67f0072 --- /dev/null +++ b/src/resources/subscription_lifetime_usage.yaml @@ -0,0 +1,53 @@ +parameters: + - name: external_id + in: path + description: External ID of the existing subscription + required: true + schema: + type: string + example: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" +get: + tags: + - subscriptions + summary: Retrive subscription lifetime usage + description: This endpoint enables the retrieval of the lifetime usage of a subscription. + operationId: getSubscriptionLifetimeUsage + responses: + "200": + description: Subscription lifetime usage + content: + application/json: + schema: + $ref: "../schemas/LifetimeUsage.yaml" + "401": + $ref: "../responses/Unauthorized.yaml" + "404": + $ref: "../responses/NotFound.yaml" +put: + tags: + - subscriptions + summary: Update a subscription lifetime usage + description: This endpoint allows you to update the lifetime usage of a subscription. + operationId: updateSubscriptionLifetimeUsage + requestBody: + description: Update the lifetime usage of a subscription + content: + application/json: + schema: + $ref: "../schemas/LifetimeUsageInput.yaml" + required: true + responses: + "200": + description: Subscription lifetime usage updated + content: + application/json: + schema: + $ref: "../schemas/LifetimeUsage.yaml" + "400": + $ref: "../responses/BadRequest.yaml" + "401": + $ref: "../responses/Unauthorized.yaml" + "404": + $ref: "../responses/NotFound.yaml" + "422": + $ref: "../responses/UnprocessableEntity.yaml" diff --git a/src/schemas/LifetimeUsage.yaml b/src/schemas/LifetimeUsage.yaml new file mode 100644 index 0000000..59937dc --- /dev/null +++ b/src/schemas/LifetimeUsage.yaml @@ -0,0 +1,6 @@ +type: object +required: + - lifetime_usage +properties: + lifetime_usage: + $ref: "./LifetimeUsageObject.yaml" diff --git a/src/schemas/LifetimeUsageInput.yaml b/src/schemas/LifetimeUsageInput.yaml new file mode 100644 index 0000000..edc6a11 --- /dev/null +++ b/src/schemas/LifetimeUsageInput.yaml @@ -0,0 +1,13 @@ +type: object +required: + - lifetime_usage +properties: + lifetime_usage: + type: object + required: + - external_historical_usage_amount_cents + properties: + external_historical_usage_amount_cents: + type: integer + example: 100 + description: The historical usage amount in cents for the subscription (provided by your own application). diff --git a/src/schemas/LifetimeUsageObject.yaml b/src/schemas/LifetimeUsageObject.yaml new file mode 100644 index 0000000..bccfc46 --- /dev/null +++ b/src/schemas/LifetimeUsageObject.yaml @@ -0,0 +1,52 @@ +type: object +required: + - lago_id + - lago_subscription_id + - external_subscription_id + - external_historical_usage_amount_cents + - invoiced_usage_amount_cents + - current_usage_amount_cents + - from_datetime + - to_datetime +properties: + lago_id: + type: string + format: "uuid" + example: "1a901a90-1a90-1a90-1a90-1a901a901a90" + description: Unique identifier assigned to the lifetime usage record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the lifetime usage record within the Lago system + lago_subscription_id: + type: string + format: "uuid" + example: "1a901a90-1a90-1a90-1a90-1a901a901a90" + description: Unique identifier assigned to the subscription record within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscription record within the Lago system + external_subscription_id: + type: string + example: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba" + description: The subscription external unique identifier (provided by your own application). + external_historical_usage_amount_cents: + type: integer + example: 100 + description: The historical usage amount in cents for the subscription (provided by your own application). + invoiced_usage_amount_cents: + type: integer + example: 100 + description: The total invoiced usage amount in cents for the subscription. + current_usage_amount_cents: + type: integer + example: 100 + description: The current usage amount in cents for the subscription on the current billing period. + from_datetime: + type: string + format: date-time + example: "2024-01-01T00:00:00Z" + description: The recording start date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format. + to_datetime: + type: string + format: date-time + example: "2024-12-31T23:59:59Z" + description: The recording end date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format. + usage_thresholds: + type: array + description: Array of usage thresholds attached to the subscription's plan. + items: + $ref: "./LifetimeUsageThresholdObject.yaml" diff --git a/src/schemas/LifetimeUsageThresholdObject.yaml b/src/schemas/LifetimeUsageThresholdObject.yaml new file mode 100644 index 0000000..d1ff974 --- /dev/null +++ b/src/schemas/LifetimeUsageThresholdObject.yaml @@ -0,0 +1,20 @@ +type: object +required: + - amount_cents + - completion_ratio + - reached_at +properties: + amount_cents: + type: integer + description: The usage threshold amount in cents. + example: 100 + completion_ratio: + type: number + description: The completion ratio of the usage threshold. + example: 0.5 + reached_at: + type: string + format: date-time + description: The date and time when the usage threshold was reached. The date and time must be in ISO 8601 format. + example: "2024-01-01T00:00:00Z" + nullable: true diff --git a/src/schemas/_index.yaml b/src/schemas/_index.yaml index 3e4f3a3..47ddc03 100644 --- a/src/schemas/_index.yaml +++ b/src/schemas/_index.yaml @@ -152,6 +152,14 @@ GrossRevenueObject: $ref: "./GrossRevenueObject.yaml" GrossRevenues: $ref: "./GrossRevenues.yaml" +LifetimeUsage: + $ref: "./LifetimeUsage.yaml" +LifetimeUsageInput: + $ref: "./LifetimeUsageInput.yaml" +LifetimeUsageObject: + $ref: "./LifetimeUsageObject.yaml" +LifetimeUsageThresholdObject: + $ref: "./LifetimeUsageThresholdObject.yaml" MinimumCommitmentInput: $ref: "./MinimumCommitmentInput.yaml" MinimumCommitmentObject: