HighLevel: List Coupons

← Payments operations · Get started

Operation gohighlevel.list_coupons

Provider route: GET /payments/coupon/list. 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"]["listCoupons"]>[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.listCoupons(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.list_coupons(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Required within parent	Additional keys: not allowed
query.altId	string	Required within parent
query.altType	string	Required within parent	One of: location
query.limit	number	Optional	Default: 100
query.offset	number	Optional	Default: 0
query.status	string	Optional	One of: scheduled, active, expired
query.search	string	Optional

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 List Coupons — response body

Referenced models: List Coupons — response body

Schemas

List Coupons — response body

Field	Type	Presence	Description and constraints
$	object	Root
data	array	Required within parent	Array of coupon objects
data[]	Model	Each item	Expand List Coupons — response body — data item
totalCount	JSON	Required within parent
totalCount (anyOf 1)	number	Alternative	Total number of coupons matching the query criteria
totalCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
traceId	string	Required within parent	Unique identifier for tracing this API request

Referenced models: List Coupons — response body — data item

List Coupons — response body — data item

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
priceIds	array	Optional	Price Ids
priceIds[]	string	Each item
productIds	array	Optional	Product Ids
productIds[]	string	Each item
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
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)
variantIds	array	Optional	Variant Ids
variantIds[]	string	Each item

Referenced models: Fetch Coupon — response body — applyToFuturePaymentsConfig / type: 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.list_coupons. Catalog operation: list-coupons. 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.readonly"]

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

Official provider source