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
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lago/refs/heads/main/openapi/lago-coupons-api-openapi.yml