> ## Documentation Index > Fetch the complete documentation index at: https://docs.getlago.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a coupon > This endpoint is used to create a coupon that can be then attached to a customer to create a discount. ```bash cURL theme={"dark"} LAGO_URL="https://api.getlago.com" API_KEY="__YOUR_API_KEY__" curl --location --request POST "$LAGO_URL/api/v1/coupons" \ --header "Authorization: Bearer $API_KEY" \ --header 'Content-Type: application/json' \ --data-raw '{ "coupon": { "name": "Startup Deal", "code": "startup_deal", "amount_cents": 5000, "amount_currency": "USD", "coupon_type": "fixed_amount", "reusable": true, "frequency": "recurring", "frequency_duration": 6, "expiration": "time_limit", "expiration_at": "2022-08-08T23:59:59Z", "applies_to": { "plan_codes": ["startup_plan"], "billable_metric_codes": [] } } }' ``` ```python Python theme={"dark"} from lago_python_client.client import Client from lago_python_client.exceptions import LagoApiError from lago_python_client.models import Coupon client = Client(api_key='__YOUR_API_KEY__') coupon = Coupon( name='Startup Deal', code='startup_deal', amount_cents=5000, amount_currency='USD', coupon_type='fixed_amount', frequency='recurring', frequency_duration=6, reusable=True expiration='time_limit', expiration_at='2022-08-08T23:59:59Z', applies_to=LimitationConfiguration(plan_codes=['startup_plan']) ) try: client.coupons.create(coupon) except LagoApiError as e: repair_broken_state(e) # do something on error or raise your own exception ``` ```ruby Ruby theme={"dark"} require 'lago-ruby-client' client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__') coupon = { name: 'Startup Deal', code: 'startup_deal', expiration: 'time_limit', expiration_at: '2022-08-08T23:59:59Z', amount_cents: 5000, amount_currency: 'USD', coupon_type: 'fixed_amount', reusable: true, frequency: 'recurring', frequency_duration: 6, applies_to: { plan_codes: ['startup_plan'] } } client.coupons.create(coupon) ``` ```js Javascript theme={"dark"} const couponObject = { name: "Startup Deal", code: "startup_deal", expiration: "time_limit" as CouponObject["expiration"], expiration_at: "2022-08-08T23:59:59Z", amount_cents: 5000, amount_currency: "USD", coupon_type: "fixed_amount" as CouponObject["couponType"], reusable: true, frequency: "recurring" as CouponObject["frequency"], frequency_duration: 6, applies_to: { plan_codes: ["startup_plan"], }, }; await client.coupons.createCoupon({ coupon: couponObject }); ``` ```go Go theme={"dark"} import "fmt" import "github.com/getlago/lago-go-client" func main() { lagoClient := lago.New(). SetApiKey("__YOUR_API_KEY__") limitationInput := &lago.LimitationInput{ PlanCodes: []string{"startup_plan"} } expirationAt := time.Date(2022, 8, 8, 23, 59, 59, 0, time.UTC) couponInput := &lago.CouponInput{ Name: "Startup Deal", Code: "startup_deal", AmountCents: 5000, AmountCurrency: lago.USD, Reusable: true, Expiration: lago.CouponExpirationTimeLimit, ExpirationAt: &expirationAt, CouponType: lago.CouponTypeFixedAmount, Frequency: lago.CouponFrequencyRecurring, FrequencyDuration: 6, AppliesTo limitationInput } coupon, err := lagoClient.Coupon().Create(couponInput) if err != nil { // Error is *lago.Error panic(err) } // coupon is *lago.Coupon fmt.Println(coupon) } ``` ## OpenAPI ````yaml POST /coupons openapi: 3.1.0 info: title: Lago API documentation description: >- Lago API allows your application to push customer information and metrics (events) from your application to the billing application. version: 1.46.0 license: name: AGPLv3 url: https://github.com/getlago/lago-openapi/blob/main/LICENSE 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 Lago cluster security: - bearerAuth: [] tags: - name: activity_logs description: Everything about Activity logs externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/audit-logs/activity-logs-object - name: analytics description: Everything about Analytics - name: api_logs description: Everything about API logs externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/audit-logs/api-logs-object - name: billable_metrics description: Everything about Billable metric collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/billable-metrics/object - name: features description: Everything about Feature collection externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/entitlements/features/feature-object - name: entitlements description: Everything about Entitlement collection externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/entitlements/plan-entitlements/plan-entitlement-object - name: billing_entities description: Everything about Billing Entities externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/billing-entities/object - name: customers description: Everything about Customer collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/customers/object - name: plans description: Everything about Plan collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/plans/object - name: subscriptions description: Everything about Subscription collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/subscriptions/subscription-object - name: events description: Everything about Event collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/events/event-object - name: organizations description: Everything about Organization collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/organizations/organization-object - name: taxes description: Everything about Tax collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/taxes/tax-object - name: coupons description: Everything about Coupon collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/coupons/coupon-object - name: add_ons description: Everything about Add-on collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/add-ons/add-on-object - name: fees description: Everything about Fees externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/invoices/invoice-object#fee-object - name: invoices description: Everything about Invoice collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/invoices/invoice-object - name: wallets description: Everything about Wallet collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/wallets/wallet-object - name: credit_notes description: Everything about Credit notes collection externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/credit-notes/credit-note-object - name: webhooks description: Everything about Webhooks externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/webhooks/format---signature#1-retrieve-the-public-key - name: webhook_endpoints description: Everything about Webhook Endpoints externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/webhook-endpoints/webhook-endpoint-object - name: payment_receipts description: Everything about Payment receipts externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/payment-receipts/payment-receipt-object - name: payment_requests description: Everything about PaymentRequests externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/payment-requests/payment-request-object - name: payments description: Everything about Payments externalDocs: description: Find out more url: https://getlago.com/docs/api-reference/payments/payment-object - name: payment_methods description: Everything about Payment Methods externalDocs: description: Find out more url: >- https://getlago.com/docs/api-reference/payment-methods/payment-method-object externalDocs: description: Lago Github url: https://github.com/getlago paths: /coupons: post: tags: - coupons summary: 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' components: schemas: CouponCreateInput: type: object required: - coupon properties: coupon: $ref: '#/components/schemas/CouponBaseInput' required: - name - code - coupon_type - frequency - expiration Coupon: type: object required: - coupon properties: coupon: $ref: '#/components/schemas/CouponObject' 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 - 'null' 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 - 'null' description: >- The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. example: 5000 amount_currency: $ref: '#/components/schemas/CurrencyOrNull' 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: false percentage_rate: type: - string - 'null' pattern: ^[0-9]+.?[0-9]*$ 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 - 'null' 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 - 'null' format: date-time 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 - 'null' description: Set coupon limitations to plans or specific metrics. properties: plan_codes: type: - array - 'null' 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 - 'null' 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: [] 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 - 'null' 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 - 'null' description: >- The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type. example: 5000 amount_currency: $ref: '#/components/schemas/CurrencyOrNull' 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 - 'null' pattern: ^[0-9]+.?[0-9]*$ 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 - 'null' 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 - 'null' format: date-time 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 - 'null' 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' ApiErrorBadRequest: type: object required: - status - error properties: status: type: integer format: int32 example: 400 error: type: string example: Bad request ApiErrorUnauthorized: type: object required: - status - error properties: status: type: integer format: int32 example: 401 error: type: string example: Unauthorized 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 CurrencyOrNull: type: - string - 'null' example: USD enum: - null - 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 responses: BadRequest: description: Bad Request error content: application/json: schema: $ref: '#/components/schemas/ApiErrorBadRequest' Unauthorized: description: Unauthorized error content: application/json: schema: $ref: '#/components/schemas/ApiErrorUnauthorized' UnprocessableEntity: description: Unprocessable entity error content: application/json: schema: $ref: '#/components/schemas/ApiErrorUnprocessableEntity' securitySchemes: bearerAuth: type: http scheme: bearer ````