HighLevel: Create Coupon

← Payments operations · Get started

Operation gohighlevel.create_coupon

Provider route: POST /payments/coupon. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/gohighlevel with npm, or alter-sdk-gohighlevel with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { HighLevelIntegration } from "@alter-ai/gohighlevel";

async function execute(input: Parameters<HighLevelIntegration["payments"]["createCoupon"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new HighLevelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.payments.createCoupon(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_gohighlevel import HighLevelIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = HighLevelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.payments.create_coupon(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Required within parent	Expand Create Coupon — request body — body

Referenced models: Create Coupon — request body — body

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Fetch Coupon — response body

Referenced models: Fetch Coupon — response body

Schemas

Create Coupon — request body — body

Field	Type	Presence	Description and constraints
$	object	Root
altId	string	Required within parent	Location Id
altType	string	Required within parent	Alt Type One of: location
applyToFuturePayments	boolean	Optional	Is Coupon applicable on upcoming subscription transactions Default: true
applyToFuturePaymentsConfig	JSON	Optional	If coupon is applicable on upcoming subscription transactions, how many months should it be applicable for a subscription Default: {"type": "forever"}
applyToFuturePaymentsConfig (allOf 1)	Model	All variants apply	Expand Create Coupon — request body — body / applyToFuturePaymentsConfig / durationType: months, type: forever, fixed
code	string	Required within parent	Coupon Code
discountType	string	Required within parent	Discount Type One of: percentage, amount
discountValue	number	Required within parent	Discount Value
endDate	string	Optional	End date in YYYY-MM-DDTHH:mm:ssZ format
limitPerCustomer	boolean	Optional	Limits whether a coupon can be redeemed only once per customer. Default: false
name	string	Required within parent	Coupon Name
priceIds	array	Optional	Price Ids
priceIds[]	string	Each item
productIds	array	Optional	Product Ids
productIds[]	string	Each item
startDate	string	Required within parent	Start date in YYYY-MM-DDTHH:mm:ssZ format
usageLimit	number	Optional	Max number of times coupon can be used
variantIds	array	Optional	Variant Ids
variantIds[]	string	Each item

Referenced models: Create Coupon — request body — body / applyToFuturePaymentsConfig / durationType: months, type: forever, fixed

Fetch Coupon — response body

Field	Type	Presence	Description and constraints
$	object	Root
_id	string	Required within parent	Unique MongoDB identifier for the coupon
altId	string	Required within parent	Location Id
altType	string	Required within parent	Type of entity
applyToFuturePayments	boolean	Required within parent	Indicates if the coupon applies to future recurring payments
applyToFuturePaymentsConfig	JSON	Required within parent	Configuration for how the coupon applies to future payments
applyToFuturePaymentsConfig (allOf 1)	Model	All variants apply	Expand Fetch Coupon — response body — applyToFuturePaymentsConfig / type: forever, fixed
code	string	Required within parent	Redemption code for the coupon
createdAt	string	Required within parent	Creation timestamp
discountType	string	Required within parent	Type of discount (percentage or amount) Known values: percentage, amount
discountValue	JSON	Required within parent
discountValue (anyOf 1)	number	Alternative	Value of the discount (percentage or fixed amount)
discountValue (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
endDate	string	Optional	End date when the coupon expires
limitPerCustomer	JSON	Required within parent
limitPerCustomer (anyOf 1)	number	Alternative	Maximum number of times a customer can use this coupon (0 for unlimited)
limitPerCustomer (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
name	string	Required within parent	Display name of the coupon
startDate	string	Required within parent	Date when the coupon becomes active
status	string	Required within parent	Current status of the coupon Known values: scheduled, active, expired
traceId	string	Required within parent	Unique identifier for tracing this API request
updatedAt	string	Required within parent	Last update timestamp
usageCount	JSON	Required within parent
usageCount (anyOf 1)	number	Alternative	Number of times the coupon has been used
usageCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
userId	string	Optional	User ID associated with the coupon (if applicable)

Referenced models: Fetch Coupon — response body — applyToFuturePaymentsConfig / type: forever, fixed

Create Coupon — request body — body / applyToFuturePaymentsConfig / durationType: months, type: forever, fixed

Field	Type	Presence	Description and constraints
$	object	Root
duration	number	Required within parent	Duration the coupon to be applied in a subscription
durationType	string	Required within parent	Type of the duration One of: months
type	string	Required within parent	Type of the config One of: forever, fixed

Fetch Coupon — response body — applyToFuturePaymentsConfig / type: forever, fixed

Field	Type	Presence	Description and constraints
$	object	Root
duration	JSON	Optional
duration (anyOf 1)	number	Alternative	Duration value for fixed type configurations
duration (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
durationType	string	Optional	Duration type for fixed configurations (e.g. months)
type	string	Required within parent	Type of future payments configuration Known values: forever, fixed

Policy, approvals and errors

SDK function policy ID: gohighlevel.create_coupon. Catalog operation: create-coupon. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["payments/coupons.write"]

Pinned headers: {"Version": "v3"}

Official provider source