openapi: 3.1.0 info: title: Lago API documentation Add_ons Coupons API description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application. version: 1.15.0 license: name: AGPLv3 identifier: AGPLv3 contact: email: tech@getlago.com servers: - url: https://api.getlago.com/api/v1 description: US Lago cluster - url: https://api.eu.getlago.com/api/v1 description: EU Lagos cluster security: - bearerAuth: [] tags: - name: Coupons description: Everything about Coupon collection externalDocs: description: Find out more url: https://doc.getlago.com/docs/api/coupons/coupon-object paths: /applied_coupons: post: tags: - Coupons summary: Lago Apply a coupon to a customer description: This endpoint is used to apply a specific coupon to a customer, before or during a subscription. operationId: applyCoupon requestBody: description: Apply coupon payload content: application/json: schema: $ref: '#/components/schemas/AppliedCouponInput' required: true responses: '200': description: Coupon applied content: application/json: schema: $ref: '#/components/schemas/AppliedCoupon' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' get: tags: - Coupons summary: Lago List all applied coupons description: This endpoint is used to list all applied coupons. You can filter by coupon status and by customer. operationId: findAllAppliedCoupons parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/per_page' - name: status in: query description: The status of the coupon. Can be either `active` or `terminated`. required: false explode: true schema: type: string enum: - active - terminated example: active - name: external_customer_id in: query description: The customer external unique identifier (provided by your own application) required: false explode: true schema: type: string example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba responses: '200': description: Applied Coupons content: application/json: schema: $ref: '#/components/schemas/AppliedCouponsPaginated' '401': $ref: '#/components/responses/Unauthorized' /coupons: post: tags: - Coupons summary: Lago Create a coupon description: This endpoint is used to create a coupon that can be then attached to a customer to create a discount. operationId: createCoupon requestBody: description: Coupon payload content: application/json: schema: $ref: '#/components/schemas/CouponCreateInput' required: true responses: '200': description: Coupon created content: application/json: schema: $ref: '#/components/schemas/Coupon' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/UnprocessableEntity' get: tags: - Coupons summary: Lago List all coupons description: This endpoint is used to list all existing coupons. operationId: findAllCoupons parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/per_page' responses: '200': description: Coupons content: application/json: schema: $ref: '#/components/schemas/CouponsPaginated' '401': $ref: '#/components/responses/Unauthorized' /coupons/{code}: parameters: - name: code in: path description: Unique code used to identify the coupon. required: true schema: type: string example: startup_deal put: tags: - Coupons summary: Lago Update a coupon description: This endpoint is used to update a coupon that can be then attached to a customer to create a discount. operationId: updateCoupon requestBody: description: Coupon payload content: application/json: schema: $ref: '#/components/schemas/CouponUpdateInput' required: true responses: '200': description: Coupon updated content: application/json: schema: $ref: '#/components/schemas/Coupon' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' get: tags: - Coupons summary: Lago Retrieve a coupon description: This endpoint is used to retrieve a specific coupon. operationId: findCoupon responses: '200': description: Coupon content: application/json: schema: $ref: '#/components/schemas/Coupon' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: tags: - Coupons summary: Lago Delete a coupon description: This endpoint is used to delete a coupon. operationId: destroyCoupon responses: '200': description: Coupon deleted content: application/json: schema: $ref: '#/components/schemas/Coupon' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /customers/{external_customer_id}/applied_coupons/{applied_coupon_id}: delete: tags: - Coupons summary: Lago Delete an applied coupon description: This endpoint is used to delete a specific coupon that has been applied to a customer. parameters: - name: external_customer_id in: path description: The customer external unique identifier (provided by your own application) required: true schema: type: string example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba - name: applied_coupon_id in: path description: Unique identifier of the applied coupon, created by Lago. required: true explode: true schema: type: string format: uuid example: 1a901a90-1a90-1a90-1a90-1a901a901a90 operationId: deleteAppliedCoupon responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AppliedCoupon' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: schemas: PaginationMeta: type: object required: - current_page - total_pages - total_count properties: current_page: type: integer description: Current page. example: 2 next_page: type: integer description: Next page. example: 3 nullable: true prev_page: type: integer description: Previous page. example: 1 nullable: true total_pages: type: integer description: Total number of pages. example: 4 total_count: type: integer description: Total number of records. example: 70 CreditObject: type: object required: - lago_id - item - amount_cents - amount_currency - invoice - before_taxes properties: lago_id: type: string format: uuid description: Unique identifier assigned to the credit within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the credit's item record within the Lago system. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 amount_cents: type: integer description: The amount of credit associated with the invoice, expressed in cents. example: 1200 amount_currency: allOf: - $ref: '#/components/schemas/Currency' - description: The currency of the credit. example: EUR before_taxes: type: boolean description: Indicates whether the credit is applied on the amount before taxes (coupons) or after taxes (credit notes). This flag helps determine the order in which credits are applied to the invoice calculation example: false item: type: object description: The item attached to the credit. required: - lago_item_id - type - code - name properties: lago_item_id: type: string format: uuid description: Unique identifier assigned to the credit item within the Lago application. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 type: type: string enum: - coupon - credit_note - invoice description: The type of credit applied. Possible values are `coupon`, `credit_note` or `invoice` (for `progressive_billing` invoice). example: coupon code: type: string description: The code of the credit applied. It can be the code of the coupon attached to the credit, the credit note's number or the `progressive_billing` invoice number. example: startup_deal name: type: string description: The name of the credit applied. It can be the name of the coupon attached to the credit, the initial invoice's number linked to the credit note or the `progressive_billing` invoice number. example: Startup Deal invoice: type: object required: - lago_id - payment_status properties: lago_id: type: string format: uuid example: 1a901a90-1a90-1a90-1a90-1a901a901a90 payment_status: type: string enum: - pending - succeeded - failed example: succeeded AppliedCouponObject: type: object required: - lago_id - lago_coupon_id - coupon_code - coupon_name - external_customer_id - lago_customer_id - status - frequency - created_at properties: lago_id: type: string format: uuid description: Unique identifier of the applied coupon, created by Lago. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 lago_coupon_id: type: string format: uuid description: Unique identifier of the coupon, created by Lago. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 coupon_code: type: string description: Unique code used to identify the coupon. example: startup_deal coupon_name: type: string description: The name of the coupon. example: Startup Deal lago_customer_id: type: string format: uuid description: Unique identifier of the customer, created by Lago. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 external_customer_id: type: string description: The customer external unique identifier (provided by your own application) example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba status: type: string enum: - active - terminated description: The status of the coupon. Can be either `active` or `terminated`. example: active amount_cents: type: integer nullable: true description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. example: 2000 amount_cents_remaining: type: integer nullable: true description: The remaining amount in cents for a `fixed_amount` coupon with a frequency set to `once`. This field indicates the remaining balance or value that can still be utilized from the coupon. example: 50 amount_currency: allOf: - $ref: '#/components/schemas/Currency' - nullable: true description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type. example: EUR percentage_rate: type: string pattern: ^[0-9]+.?[0-9]*$ nullable: true description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. example: null frequency: type: string enum: - once - recurring - forever description: 'The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`. - If set to `once`, the coupon is applicable only for a single use. - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.' example: recurring frequency_duration: type: integer nullable: true description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type example: 3 frequency_duration_remaining: type: integer nullable: true description: The remaining number of billing periods to which the coupon is applicable. This field determines the remaining usage or availability of the coupon based on the remaining billing periods. example: 1 expiration_at: type: string format: date-time nullable: true description: The date and time after which the coupon will stop applying to customer's invoices. Once the expiration date is reached, the coupon will no longer be applicable, and any further invoices generated for the customer will not include the coupon discount. example: '2022-04-29T08:59:51Z' created_at: type: string format: date-time description: The date and time when the coupon was assigned to a customer. It is expressed in UTC format according to the ISO 8601 datetime standard. example: '2022-04-29T08:59:51Z' terminated_at: type: string format: date-time nullable: true description: This field indicates the specific moment when the coupon amount is fully utilized or when the coupon is removed from the customer's coupon list. It is expressed in UTC format according to the ISO 8601 datetime standard. example: '2022-04-29T08:59:51Z' CouponCreateInput: type: object required: - coupon properties: coupon: allOf: - $ref: '#/components/schemas/CouponBaseInput' - required: - name - code - coupon_type - frequency - expiration CouponBaseInput: type: object properties: name: type: string description: The name of the coupon. example: Startup Deal code: type: string description: Unique code used to identify the coupon. example: startup_deal description: type: string nullable: true description: Description of the coupon. example: I am a coupon description coupon_type: type: string enum: - fixed_amount - percentage description: 'The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`. - If set to `fixed_amount`, the coupon represents a fixed amount discount. - If set to `percentage`, the coupon represents a percentage-based discount.' example: fixed_amount amount_cents: type: integer nullable: true description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. example: 5000 amount_currency: allOf: - $ref: '#/components/schemas/Currency' - description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type. nullable: true example: USD reusable: type: boolean description: Indicates whether the coupon can be reused or not. If set to `true`, the coupon is reusable, meaning it can be applied multiple times to the same customer. If set to `false`, the coupon can only be used once and is not reusable. If not specified, this field is set to `true` by default. example: false percentage_rate: type: string pattern: ^[0-9]+.?[0-9]*$ nullable: true description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. example: null frequency: type: string enum: - once - recurring - forever description: 'The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`. - If set to `once`, the coupon is applicable only for a single use. - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.' example: recurring frequency_duration: type: integer nullable: true description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type example: 6 expiration: type: string enum: - no_expiration - time_limit description: 'Specifies the type of expiration for the coupon. It can have two possible values: `time_limit` or `no_expiration`. - If set to `time_limit`, the coupon has an expiration based on a specified time limit. - If set to `no_expiration`, the coupon does not have an expiration date and remains valid indefinitely.' example: time_limit expiration_at: type: string format: date-time nullable: true description: The expiration date and time of the coupon. This field is required only for coupons with `expiration` set to `time_limit`. The expiration date and time should be specified in UTC format according to the ISO 8601 datetime standard. It indicates the exact moment when the coupon will expire and is no longer valid. example: '2022-08-08T23:59:59Z' applies_to: type: object description: Set coupon limitations to plans or specific metrics. nullable: true properties: plan_codes: type: array nullable: true items: type: string description: An array of plan codes to which the coupon is applicable. By specifying the plan codes in this field, you can restrict the coupon's usage to specific plans only. example: - startup_plan billable_metric_codes: type: array nullable: true items: type: string description: An array of billable metric codes to which the coupon is applicable. By specifying the billable metric codes in this field, you can restrict the coupon's usage to specific metrics only. example: [] ApiErrorNotFound: type: object required: - status - error - code properties: status: type: integer format: int32 example: 404 error: type: string example: Not Found code: type: string example: object_not_found Coupon: type: object required: - coupon properties: coupon: $ref: '#/components/schemas/CouponObject' CouponsPaginated: type: object required: - coupons - meta properties: coupons: type: array items: $ref: '#/components/schemas/CouponObject' meta: $ref: '#/components/schemas/PaginationMeta' ApiErrorUnprocessableEntity: type: object required: - status - error - code - error_details properties: status: type: integer format: int32 example: 422 error: type: string example: Unprocessable entity code: type: string example: validation_errors error_details: type: object AppliedCouponInput: type: object required: - applied_coupon properties: applied_coupon: type: object required: - external_customer_id - coupon_code properties: external_customer_id: type: string description: The customer external unique identifier (provided by your own application) example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba coupon_code: type: string description: Unique code used to identify the coupon. example: startup_deal frequency: type: string enum: - once - recurring - forever nullable: true description: 'The type of frequency for the coupon. It can have three possible values: `once`, `recurring` or `forever`. - If set to `once`, the coupon is applicable only for a single use. - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.' example: recurring frequency_duration: type: integer nullable: true description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type example: 3 amount_cents: type: integer nullable: true description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. example: 2000 amount_currency: allOf: - $ref: '#/components/schemas/Currency' - nullable: true description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type. example: EUR percentage_rate: type: string pattern: ^[0-9]+.?[0-9]*$ nullable: true description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. example: null ApiErrorUnauthorized: type: object required: - status - error properties: status: type: integer format: int32 example: 401 error: type: string example: Unauthorized ApiErrorBadRequest: type: object required: - status - error properties: status: type: integer format: int32 example: 400 error: type: string example: Bad request Currency: type: string example: USD enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BIF - BMD - BND - BOB - BRL - BSD - BWP - BYN - BZD - CAD - CDF - CHF - CLF - CLP - CNY - COP - CRC - CVE - CZK - DJF - DKK - DOP - DZD - EGP - ETB - EUR - FJD - FKP - GBP - GEL - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - ISK - JMD - JPY - KES - KGS - KHR - KMF - KRW - KYD - KZT - LAK - LBP - LKR - LRD - LSL - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MUR - MVR - MWK - MXN - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SEK - SGD - SHP - SLL - SOS - SRD - STD - SZL - THB - TJS - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - UYU - UZS - VND - VUV - WST - XAF - XCD - XOF - XPF - YER - ZAR - ZMW CouponUpdateInput: type: object required: - coupon properties: coupon: allOf: - $ref: '#/components/schemas/CouponBaseInput' AppliedCouponsPaginated: type: object required: - applied_coupons - meta properties: applied_coupons: type: array items: $ref: '#/components/schemas/AppliedCouponObjectExtended' meta: $ref: '#/components/schemas/PaginationMeta' CouponObject: type: object required: - lago_id - name - code - expiration - coupon_type - frequency - created_at - reusable - limited_plans - limited_billable_metrics properties: lago_id: type: string format: uuid description: Unique identifier of the coupon, created by Lago. example: 1a901a90-1a90-1a90-1a90-1a901a901a90 name: type: string description: The name of the coupon. example: Startup Deal code: type: string description: Unique code used to identify the coupon. example: startup_deal description: type: string nullable: true description: Description of the coupon. example: I am a coupon description coupon_type: type: string enum: - fixed_amount - percentage description: 'The type of the coupon. It can have two possible values: `fixed_amount` or `percentage`. - If set to `fixed_amount`, the coupon represents a fixed amount discount. - If set to `percentage`, the coupon represents a percentage-based discount.' example: fixed_amount amount_cents: type: integer nullable: true description: The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. example: 5000 amount_currency: allOf: - $ref: '#/components/schemas/Currency' - nullable: true description: The currency of the coupon. This field is required only for coupon with `fixed_amount` type. example: USD reusable: type: boolean description: Indicates whether the coupon can be reused or not. If set to `true`, the coupon is reusable, meaning it can be applied multiple times to the same customer. If set to `false`, the coupon can only be used once and is not reusable. If not specified, this field is set to `true` by default. example: true limited_plans: type: boolean description: The coupon is limited to specific plans. The possible values can be `true` or `false`. example: true plan_codes: type: array description: An array of plan codes to which the coupon is applicable. By specifying the plan codes in this field, you can restrict the coupon's usage to specific plans only. items: type: string example: - startup_plan limited_billable_metrics: type: boolean description: The coupon is limited to specific billable metrics. The possible values can be `true` or `false`. example: false billable_metric_codes: type: array description: An array of billable metric codes to which the coupon is applicable. By specifying the billable metric codes in this field, you can restrict the coupon's usage to specific metrics only. items: type: string example: [] percentage_rate: type: string pattern: ^[0-9]+.?[0-9]*$ nullable: true description: The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type. example: null frequency: type: string description: 'The type of frequency for the coupon. It can have three possible values: `once`, `recurring`, or `forever`. - If set to `once`, the coupon is applicable only for a single use. - If set to `recurring`, the coupon can be used multiple times for recurring billing periods. - If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.' enum: - once - recurring - forever example: recurring frequency_duration: type: integer nullable: true description: Specifies the number of billing periods to which the coupon applies. This field is required only for coupons with a `recurring` frequency type example: 6 expiration: type: string description: 'Specifies the type of expiration for the coupon. It can have two possible values: `time_limit` or `no_expiration`. - If set to `time_limit`, the coupon has an expiration based on a specified time limit. - If set to `no_expiration`, the coupon does not have an expiration date and remains valid indefinitely.' enum: - no_expiration - time_limit example: time_limit expiration_at: type: string format: date-time nullable: true description: The expiration date and time of the coupon. This field is required only for coupons with `expiration` set to `time_limit`. The expiration date and time should be specified in UTC format according to the ISO 8601 datetime standard. It indicates the exact moment when the coupon will expire and is no longer valid. example: '2022-08-08T23:59:59Z' created_at: type: string format: date-time description: The date and time when the coupon was created. It is expressed in UTC format according to the ISO 8601 datetime standard. This field provides the timestamp for the exact moment when the coupon was initially created. example: '2022-04-29T08:59:51Z' terminated_at: type: string format: date-time description: This field indicates if the coupon has been terminated and is no longer usable. If it's not null, it won't be removed for existing customers using it, but it prevents the coupon from being applied in the future. example: '2022-08-08T23:59:59Z' AppliedCoupon: type: object required: - applied_coupon properties: applied_coupon: $ref: '#/components/schemas/AppliedCouponObject' AppliedCouponObjectExtended: allOf: - $ref: '#/components/schemas/AppliedCouponObject' - type: object required: - credits properties: credits: type: array items: $ref: '#/components/schemas/CreditObject' responses: BadRequest: description: Bad Request error content: application/json: schema: $ref: '#/components/schemas/ApiErrorBadRequest' NotFound: description: Not Found error content: application/json: schema: $ref: '#/components/schemas/ApiErrorNotFound' UnprocessableEntity: description: Unprocessable entity error content: application/json: schema: $ref: '#/components/schemas/ApiErrorUnprocessableEntity' Unauthorized: description: Unauthorized error content: application/json: schema: $ref: '#/components/schemas/ApiErrorUnauthorized' parameters: page: name: page in: query description: Page number. required: false explode: true schema: type: integer example: 1 per_page: name: per_page in: query description: Number of records per page. required: false explode: true schema: type: integer example: 20 securitySchemes: bearerAuth: type: http scheme: bearer externalDocs: description: Lago Github url: https://github.com/getlago