diff --git a/openapi.yaml b/openapi.yaml index 3b89551c..c2f7c2b1 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1276,8 +1276,8 @@ paths: delete: tags: - features - summary: Delete a privilege. Deleting a privilege removes it from all plans and subscriptions. - description: Delete privilege from feature. Deleting a privilege removes it from all plans and subscriptions. + summary: Delete a privilege + description: This endpoint deletes a privilege from a feature. Deleting a privilege removes it from all plans and subscriptions. operationId: deleteFeaturePrivilege responses: '200': @@ -5107,7 +5107,7 @@ paths: tags: - entitlements summary: Partial update of an entitlement - description: This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. + description: This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. operationId: updateEntitlement requestBody: description: Entitlement payload @@ -6502,7 +6502,7 @@ paths: summary: Update subscription entitlements parameters: - $ref: '#/components/parameters/subscription_status' - description: This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. + description: This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. operationId: updateSubscriptionEntitlements requestBody: description: Subscription entitlements payload @@ -6546,17 +6546,17 @@ paths: tags: - entitlements summary: Remove an entitlement from a subscription - description: This endpoint removes a specific feature entitlement from a subscription. The entitlement remains available from the plan. + description: This endpoint removes a specific feature entitlement from a subscription. The entitlement remains available from the plan. It returns the full list of entitlements remaining on the subscription. operationId: destroySubscriptionEntitlement parameters: - $ref: '#/components/parameters/subscription_status' responses: '200': - description: Subscription entitlement removed + description: Remaining subscription entitlements content: application/json: schema: - $ref: '#/components/schemas/SubscriptionEntitlement' + $ref: '#/components/schemas/SubscriptionEntitlements' '401': $ref: '#/components/responses/Unauthorized' '404': @@ -6588,17 +6588,17 @@ paths: tags: - entitlements summary: Remove a privilege from a subscription entitlement override - description: This endpoint removes a specific privilege from a subscription entitlement. The privilege entitlement remains available from the plan. + description: This endpoint removes a specific privilege from a subscription entitlement. The privilege entitlement remains available from the plan. It returns the full list of entitlements remaining on the subscription. operationId: destroySubscriptionEntitlementPrivilege parameters: - $ref: '#/components/parameters/subscription_status' responses: '200': - description: Subscription entitlement with privilege override removed + description: Remaining subscription entitlements content: application/json: schema: - $ref: '#/components/schemas/SubscriptionEntitlement' + $ref: '#/components/schemas/SubscriptionEntitlements' '400': $ref: '#/components/responses/BadRequest' '401': @@ -21733,7 +21733,9 @@ components: description: The amount of the minimum commitment in cents. example: 100000 invoice_display_name: - type: string + type: + - string + - 'null' description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. example: Minimum Commitment (C1) interval: @@ -22240,7 +22242,9 @@ components: description: Unique identifier of the add-on associated with this fixed charge. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 invoice_display_name: - type: string + type: + - string + - 'null' description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. example: Setup fee add_on_code: @@ -22299,6 +22303,27 @@ components: description: List of taxes applied to the fixed charge. items: $ref: '#/components/schemas/TaxObject' + ApplicableUsageThreshold: + type: object + required: + - threshold_display_name + - amount_cents + - recurring + properties: + threshold_display_name: + type: + - string + - 'null' + description: The display name of the usage threshold. + example: Threshold 1 + amount_cents: + type: integer + description: The amount to reach to trigger a `progressive_billing` invoice. + example: 10000 + recurring: + type: boolean + description: This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount. + example: true PlanEntitlementPrivilegeObject: allOf: - $ref: '#/components/schemas/FeaturePrivilegeObject' @@ -22397,7 +22422,9 @@ components: description: The name of the plan. example: Startup invoice_display_name: - type: string + type: + - string + - 'null' description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name. example: Startup plan created_at: @@ -22420,9 +22447,11 @@ components: - yearly example: monthly description: - type: string + type: + - string + - 'null' description: The description on the plan. - example: '' + example: Plan for early stage startups. amount_cents: type: integer description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan. @@ -22432,7 +22461,9 @@ components: description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed. example: USD trial_period: - type: number + type: + - number + - 'null' description: The duration in days during which the base cost of the plan is offered for free. example: 5 pay_in_advance: @@ -22451,6 +22482,17 @@ components: - 'null' description: This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. example: null + parent_id: + type: + - string + - 'null' + format: uuid + description: Unique identifier of the parent plan, created by Lago. It is set on plans that override a parent plan for a single subscription, and `null` on standard plans. + example: null + pending_deletion: + type: boolean + description: This field is set to `true` when the plan is scheduled for deletion but still attached to subscriptions that have to be billed first. + example: false minimum_commitment: $ref: '#/components/schemas/MinimumCommitmentObject' charges: @@ -22648,6 +22690,11 @@ components: description: List of usage thresholds applied to the plan. items: $ref: '#/components/schemas/UsageThresholdObject' + applicable_usage_thresholds: + type: array + description: List of usage thresholds that actually apply to the plan. For an overriding plan these are inherited from its parent plan; for a standard plan they match `usage_thresholds`. + items: + $ref: '#/components/schemas/ApplicableUsageThreshold' entitlements: type: array description: List of all feature entitlements and their privileges available for this plan. @@ -23028,6 +23075,11 @@ components: tax_codes: $ref: '#/components/schemas/TaxCodes' description: List of taxes applied to the fixed charge. + apply_units_immediately: + type: boolean + description: When set to `true`, the fixed charge units are applied immediately for active subscriptions. When set to `false`, the units are applied at the next billing period. + example: false + default: false example: - add_on_id: 1a901a90-1a90-1a90-1a90-1a901a901a90 code: setup_fee @@ -23038,6 +23090,7 @@ components: properties: amount: '500' units: 1 + apply_units_immediately: false tax_codes: - french_standard_vat - add_on_id: 4d604d60-4d60-4d60-4d60-4d604d604d60 @@ -24395,27 +24448,6 @@ components: $ref: '#/components/schemas/SubscriptionActivationRuleInput' description: | Optional list of activation rules that gate the subscription activation. When a `payment` rule is provided and the plan is paid in advance (and the subscription is not in a trial), the subscription is created in the `incomplete` state and is only activated once the gating payment succeeds. If the payment fails or the rule's `timeout_hours` elapses, the subscription is canceled. - ApplicableUsageThreshold: - type: object - required: - - threshold_display_name - - amount_cents - - recurring - properties: - threshold_display_name: - type: - - string - - 'null' - description: The display name of the usage threshold. - example: Threshold 1 - amount_cents: - type: integer - description: The amount to reach to trigger a `progressive_billing` invoice. - example: 10000 - recurring: - type: boolean - description: This field when set to `true` indicates that a `progressive_billing` invoice will be created every time the lifetime usage increases by the specified amount. - example: true SubscriptionObjectExtended: allOf: - $ref: '#/components/schemas/SubscriptionObject' @@ -24832,7 +24864,7 @@ components: - type: string description: Value for string or select type privileges example: 10 - description: Applicable value this this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type. + description: Applicable value for this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type. plan_value: oneOf: - type: integer @@ -24841,8 +24873,10 @@ components: description: Value for boolean type privileges - type: string description: Value for string or select type privileges + - type: 'null' + description: No plan value set example: 10 - description: Value assigned to this privilege in the plan. Type depends on the privilege's value_type. + description: Value assigned to this privilege in the plan. Type depends on the privilege's value_type. Null when the privilege only exists as a subscription override. override_value: oneOf: - type: integer @@ -24932,13 +24966,6 @@ components: type: array items: $ref: '#/components/schemas/SubscriptionEntitlementObject' - SubscriptionEntitlement: - type: object - required: - - entitlement - properties: - entitlement: - $ref: '#/components/schemas/SubscriptionEntitlementObject' SubscriptionChargeOverride: type: object required: @@ -26259,6 +26286,13 @@ components: - type: string - type: object additionalProperties: true + SubscriptionEntitlement: + type: object + required: + - entitlement + properties: + entitlement: + $ref: '#/components/schemas/SubscriptionEntitlementObject' responses: Unauthorized: description: Unauthorized error diff --git a/src/resources/feature_privilege.yml b/src/resources/feature_privilege.yml index b66436a1..23690442 100644 --- a/src/resources/feature_privilege.yml +++ b/src/resources/feature_privilege.yml @@ -16,8 +16,8 @@ parameters: delete: tags: - features - summary: Delete a privilege. Deleting a privilege removes it from all plans and subscriptions. - description: Delete privilege from feature. Deleting a privilege removes it from all plans and subscriptions. + summary: Delete a privilege + description: This endpoint deletes a privilege from a feature. Deleting a privilege removes it from all plans and subscriptions. operationId: deleteFeaturePrivilege responses: '200': diff --git a/src/resources/plan_entitlements.yaml b/src/resources/plan_entitlements.yaml index 86ccc24a..2cf932cd 100644 --- a/src/resources/plan_entitlements.yaml +++ b/src/resources/plan_entitlements.yaml @@ -55,7 +55,7 @@ patch: tags: - entitlements summary: Partial update of an entitlement - description: This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. + description: This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. operationId: updateEntitlement requestBody: description: Entitlement payload diff --git a/src/resources/subscription_entitlement.yaml b/src/resources/subscription_entitlement.yaml index f4b3ec57..59fe8d6d 100644 --- a/src/resources/subscription_entitlement.yaml +++ b/src/resources/subscription_entitlement.yaml @@ -17,17 +17,17 @@ delete: tags: - entitlements summary: Remove an entitlement from a subscription - description: This endpoint removes a specific feature entitlement from a subscription. The entitlement remains available from the plan. + description: This endpoint removes a specific feature entitlement from a subscription. The entitlement remains available from the plan. It returns the full list of entitlements remaining on the subscription. operationId: destroySubscriptionEntitlement parameters: - $ref: "../parameters/subscription_status.yaml" responses: '200': - description: Subscription entitlement removed + description: Remaining subscription entitlements content: application/json: schema: - $ref: '../schemas/Entitlement/SubscriptionEntitlement.yaml' + $ref: '../schemas/Entitlement/SubscriptionEntitlements.yaml' '401': $ref: '../responses/Unauthorized.yaml' '404': diff --git a/src/resources/subscription_entitlement_privileges.yaml b/src/resources/subscription_entitlement_privileges.yaml index cd52ed96..2dbb54cc 100644 --- a/src/resources/subscription_entitlement_privileges.yaml +++ b/src/resources/subscription_entitlement_privileges.yaml @@ -24,17 +24,17 @@ delete: tags: - entitlements summary: Remove a privilege from a subscription entitlement override - description: This endpoint removes a specific privilege from a subscription entitlement. The privilege entitlement remains available from the plan. + description: This endpoint removes a specific privilege from a subscription entitlement. The privilege entitlement remains available from the plan. It returns the full list of entitlements remaining on the subscription. operationId: destroySubscriptionEntitlementPrivilege parameters: - $ref: "../parameters/subscription_status.yaml" responses: '200': - description: Subscription entitlement with privilege override removed + description: Remaining subscription entitlements content: application/json: schema: - $ref: '../schemas/Entitlement/SubscriptionEntitlement.yaml' + $ref: '../schemas/Entitlement/SubscriptionEntitlements.yaml' '400': $ref: '../responses/BadRequest.yaml' '401': diff --git a/src/resources/subscription_entitlements.yaml b/src/resources/subscription_entitlements.yaml index ebadf92f..bb643b37 100644 --- a/src/resources/subscription_entitlements.yaml +++ b/src/resources/subscription_entitlements.yaml @@ -31,7 +31,7 @@ patch: summary: Update subscription entitlements parameters: - $ref: "../parameters/subscription_status.yaml" - description: This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. + description: This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints. operationId: updateSubscriptionEntitlements requestBody: description: Subscription entitlements payload diff --git a/src/schemas/Entitlement/SubscriptionEntitlementPrivilegeObject.yaml b/src/schemas/Entitlement/SubscriptionEntitlementPrivilegeObject.yaml index 386c1396..5e26981d 100644 --- a/src/schemas/Entitlement/SubscriptionEntitlementPrivilegeObject.yaml +++ b/src/schemas/Entitlement/SubscriptionEntitlementPrivilegeObject.yaml @@ -15,7 +15,7 @@ allOf: - type: string description: "Value for string or select type privileges" example: 10 - description: "Applicable value this this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type." + description: "Applicable value for this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type." plan_value: oneOf: - type: integer @@ -24,8 +24,10 @@ allOf: description: "Value for boolean type privileges" - type: string description: "Value for string or select type privileges" + - type: "null" + description: "No plan value set" example: 10 - description: "Value assigned to this privilege in the plan. Type depends on the privilege's value_type." + description: "Value assigned to this privilege in the plan. Type depends on the privilege's value_type. Null when the privilege only exists as a subscription override." override_value: oneOf: - type: integer diff --git a/src/schemas/FixedChargeObject.yaml b/src/schemas/FixedChargeObject.yaml index 87d9d9b4..61a625fc 100644 --- a/src/schemas/FixedChargeObject.yaml +++ b/src/schemas/FixedChargeObject.yaml @@ -23,7 +23,9 @@ properties: description: Unique identifier of the add-on associated with this fixed charge. example: "1a901a90-1a90-1a90-1a90-1a901a901a90" invoice_display_name: - type: string + type: + - string + - "null" description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the actual charge will be used as the default display name. example: "Setup fee" add_on_code: diff --git a/src/schemas/MinimumCommitmentObject.yaml b/src/schemas/MinimumCommitmentObject.yaml index e77be7db..9df4d625 100644 --- a/src/schemas/MinimumCommitmentObject.yaml +++ b/src/schemas/MinimumCommitmentObject.yaml @@ -20,7 +20,9 @@ properties: description: The amount of the minimum commitment in cents. example: 100000 invoice_display_name: - type: string + type: + - string + - "null" description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the default name will be used as the display name. example: "Minimum Commitment (C1)" interval: diff --git a/src/schemas/PlanCreateInput.yaml b/src/schemas/PlanCreateInput.yaml index da4a4da0..5f550369 100644 --- a/src/schemas/PlanCreateInput.yaml +++ b/src/schemas/PlanCreateInput.yaml @@ -293,6 +293,11 @@ properties: tax_codes: $ref: "./TaxCodes.yaml" description: List of taxes applied to the fixed charge. + apply_units_immediately: + type: boolean + description: When set to `true`, the fixed charge units are applied immediately for active subscriptions. When set to `false`, the units are applied at the next billing period. + example: false + default: false example: - add_on_id: "1a901a90-1a90-1a90-1a90-1a901a901a90" code: "setup_fee" @@ -303,6 +308,7 @@ properties: properties: amount: "500" units: 1.0 + apply_units_immediately: false tax_codes: ["french_standard_vat"] - add_on_id: "4d604d60-4d60-4d60-4d60-4d604d604d60" invoice_display_name: "Support Tier" diff --git a/src/schemas/PlanObject.yaml b/src/schemas/PlanObject.yaml index 275f5003..47925502 100644 --- a/src/schemas/PlanObject.yaml +++ b/src/schemas/PlanObject.yaml @@ -18,7 +18,9 @@ properties: description: The name of the plan. example: "Startup" invoice_display_name: - type: string + type: + - string + - "null" description: Specifies the name that will be displayed on an invoice. If no value is set for this field, the name of the plan will be used as the default display name. example: "Startup plan" created_at: @@ -41,9 +43,11 @@ properties: - yearly example: monthly description: - type: string + type: + - string + - "null" description: The description on the plan. - example: "" + example: "Plan for early stage startups." amount_cents: type: integer description: The base cost of the plan, excluding any applicable taxes, that is billed on a recurring basis. This value is defined at 0 if your plan is a pay-as-you-go plan. @@ -53,7 +57,9 @@ properties: description: The currency of the plan. It indicates the monetary unit in which the plan's cost, including taxes and usage-based charges, is expressed. example: "USD" trial_period: - type: number + type: + - number + - "null" description: The duration in days during which the base cost of the plan is offered for free. example: 5 pay_in_advance: @@ -72,6 +78,17 @@ properties: - "null" description: This field, when set to `true`, enables to invoice fixed charges on monthly basis, even if the cadence of the plan is yearly or semiannual. This allows customers to pay fixed charges on a monthly basis. This can be set to true only if the plan's interval is `yearly` or `semiannual`. example: null + parent_id: + type: + - string + - "null" + format: "uuid" + description: Unique identifier of the parent plan, created by Lago. It is set on plans that override a parent plan for a single subscription, and `null` on standard plans. + example: null + pending_deletion: + type: boolean + description: This field is set to `true` when the plan is scheduled for deletion but still attached to subscriptions that have to be billed first. + example: false minimum_commitment: $ref: "./MinimumCommitmentObject.yaml" charges: @@ -266,6 +283,11 @@ properties: description: List of usage thresholds applied to the plan. items: $ref: "./UsageThresholdObject.yaml" + applicable_usage_thresholds: + type: array + description: List of usage thresholds that actually apply to the plan. For an overriding plan these are inherited from its parent plan; for a standard plan they match `usage_thresholds`. + items: + $ref: "./ApplicableUsageThreshold.yaml" entitlements: type: array description: List of all feature entitlements and their privileges available for this plan.