Recurly · Schema
CouponCreate
SubscriptionBillingPaymentsRecurring RevenueInvoicingDunningRevenue RecognitionChurnMCPShopifyWebhook
Properties
| Name | Type | Description |
|---|---|---|
| name | string | The internal name for the coupon. |
| max_redemptions | integer | A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions. |
| max_redemptions_per_account | integer | Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to `1` if you want to keep customers from gaming the system and getting more than o |
| hosted_description | string | This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page. |
| invoice_description | string | Description of the coupon on the invoice. |
| redeem_by_date | string | The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time. Mutually exclusive with redeem_by_interval_unit/redeem_by_interval_amount. |
| redeem_by_interval_unit | object | Unit of the relative redemption window. Must be paired with redeem_by_interval_amount. Mutually exclusive with redeem_by_date. Bulk coupons only. |
| redeem_by_interval_amount | integer | Quantity of redeem_by_interval_unit. Must be paired with redeem_by_interval_unit. |
| code | string | The code the customer enters to redeem the coupon. |
| discount_type | object | The type of discount provided by the coupon (how the amount discounted is calculated) |
| discount_percent | integer | The percent of the price discounted by the coupon. Required if `discount_type` is `percent`. |
| free_trial_unit | object | Description of the unit of time the coupon is for. Used with `free_trial_amount` to determine the duration of time the coupon is for. Required if `discount_type` is `free_trial`. Use `billing_period` |
| free_trial_amount | integer | Sets the duration of time the `free_trial_unit` is for. Required if `discount_type` is `free_trial`. |
| currencies | array | Fixed discount currencies by currency. Required if the coupon type is `fixed`. This parameter should contain the coupon discount values |
| applies_to_non_plan_charges | boolean | The coupon is valid for one-time, non-plan charges if true. |
| applies_to_all_plans | boolean | The coupon is valid for all plans if true. If false then `plans` will list the applicable plans. |
| applies_to_all_items | boolean | To apply coupon to Items in your Catalog, include a list of `item_codes` in the request that the coupon will apply to. Or set value to true to apply to all Items in your Catalog. The following values |
| plan_codes | array | List of plan codes to which this coupon applies. Required if `applies_to_all_plans` is false. Overrides `applies_to_all_plans` when `applies_to_all_plans` is true. |
| item_codes | array | List of item codes to which this coupon applies. Sending `item_codes` is only permitted when `applies_to_all_items` is set to false. The following values are not permitted when `item_codes` is include |
| duration | object | This field does not apply when the discount_type is `free_trial`. - "single_use" coupons applies to the first invoice only. - "temporal" coupons will apply to invoices for the duration determined by t |
| temporal_amount | integer | If `duration` is "temporal" than `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for. When `temporal_unit` is |
| temporal_unit | object | If `duration` is "temporal" than `temporal_unit` is multiplied by `temporal_amount` to define the duration that the coupon will be applied to invoices for. Use "billing_period" to apply the coupon for |
| coupon_type | object | Whether the coupon is "single_code" or "bulk". Bulk coupons will require a `unique_code_template` and will generate unique codes through the `/generate` endpoint. |
| unique_code_template | string | On a bulk coupon, the template from which unique coupon codes are generated. - You must start the template with your coupon_code wrapped in single quotes. - Outside of single quotes, use a 9 for a cha |
| redemption_resource | object | Whether the discount is for all eligible charges on the account, or only a specific subscription. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/recurly/json-schema/recurly-coupon-create-schema.json",
"title": "CouponCreate",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/recurly-coupon-api-openapi.yml#/components/schemas/CouponCreate",
"allOf": [
{
"$ref": "#/$defs/CouponUpdate"
},
{
"type": "object",
"properties": {
"code": {
"type": "string",
"title": "Coupon code",
"description": "The code the customer enters to redeem the coupon."
},
"discount_type": {
"title": "Discount type",
"description": "The type of discount provided by the coupon (how the amount discounted is calculated)",
"$ref": "#/$defs/DiscountTypeEnum"
},
"discount_percent": {
"type": "integer",
"title": "Discount percent",
"description": "The percent of the price discounted by the coupon. Required if `discount_type` is `percent`."
},
"free_trial_unit": {
"title": "Free trial unit",
"description": "Description of the unit of time the coupon is for. Used with `free_trial_amount` to determine the duration of time the coupon is for. Required if `discount_type` is `free_trial`. Use `billing_period` to grant a free trial for a number of billing cycles.",
"$ref": "#/$defs/FreeTrialUnitEnum"
},
"free_trial_amount": {
"type": "integer",
"title": "Free trial amount",
"description": "Sets the duration of time the `free_trial_unit` is for. Required if `discount_type` is `free_trial`.",
"minimum": 1,
"maximum": 9999
},
"currencies": {
"title": "Currencies",
"description": "Fixed discount currencies by currency. Required if the coupon type is `fixed`. This parameter should contain the coupon discount values",
"type": "array",
"items": {
"$ref": "#/$defs/CouponPricing"
}
},
"applies_to_non_plan_charges": {
"type": "boolean",
"title": "Applied to all non-plan charges?",
"description": "The coupon is valid for one-time, non-plan charges if true.",
"default": false
},
"applies_to_all_plans": {
"type": "boolean",
"title": "Applies to all plans?",
"description": "The coupon is valid for all plans if true. If false then `plans` will list the applicable plans.",
"default": true
},
"applies_to_all_items": {
"type": "boolean",
"title": "Applies to all items?",
"description": "To apply coupon to Items in your Catalog, include a list\nof `item_codes` in the request that the coupon will apply to. Or set value\nto true to apply to all Items in your Catalog. The following values\nare not permitted when `applies_to_all_items` is included: `free_trial_amount`\nand `free_trial_unit`.\n",
"default": false
},
"plan_codes": {
"type": "array",
"title": "Plan codes",
"description": "List of plan codes to which this coupon applies. Required\nif `applies_to_all_plans` is false. Overrides `applies_to_all_plans`\nwhen `applies_to_all_plans` is true.\n",
"items": {
"type": "string"
}
},
"item_codes": {
"type": "array",
"title": "Item codes",
"description": "List of item codes to which this coupon applies. Sending\n`item_codes` is only permitted when `applies_to_all_items` is set to false.\nThe following values are not permitted when `item_codes` is included:\n`free_trial_amount` and `free_trial_unit`.\n",
"items": {
"type": "string"
}
},
"duration": {
"title": "Duration",
"description": "This field does not apply when the discount_type is `free_trial`.\n- \"single_use\" coupons applies to the first invoice only.\n- \"temporal\" coupons will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes.\n- \"forever\" coupons will apply to invoices forever.\n",
"default": "forever",
"$ref": "#/$defs/CouponDurationEnum"
},
"temporal_amount": {
"type": "integer",
"title": "Temporal amount",
"description": "If `duration` is \"temporal\" than `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for. When `temporal_unit` is \"billing_period\", this is the number of complete billing cycles."
},
"temporal_unit": {
"title": "Temporal unit",
"description": "If `duration` is \"temporal\" than `temporal_unit` is multiplied by `temporal_amount` to define the duration that the coupon will be applied to invoices for. Use \"billing_period\" to apply the coupon for a fixed number of billing cycles. Requires `redemption_resource=subscription`. Not compatible with `discount_type=free_trial`; use `free_trial_unit=billing_period` and `free_trial_amount` instead.",
"$ref": "#/$defs/TemporalUnitEnum"
},
"coupon_type": {
"title": "Coupon type",
"description": "Whether the coupon is \"single_code\" or \"bulk\". Bulk coupons will require a `unique_code_template` and will generate unique codes through the `/generate` endpoint.",
"$ref": "#/$defs/CouponTypeEnum"
},
"unique_code_template": {
"type": "string",
"title": "Unique code template",
"description": "On a bulk coupon, the template from which unique coupon codes are generated.\n- You must start the template with your coupon_code wrapped in single quotes.\n- Outside of single quotes, use a 9 for a character that you want to be a random number.\n- Outside of single quotes, use an \"x\" for a character that you want to be a random letter.\n- Outside of single quotes, use an * for a character that you want to be a random number or letter.\n- Use single quotes ' ' for characters that you want to remain static. These strings can be alphanumeric and may contain a - _ or +.\nFor example: \"'abc-'****'-def'\"\n"
},
"redemption_resource": {
"title": "Redemption resource",
"description": "Whether the discount is for all eligible charges on the account, or only a specific subscription.",
"default": "account",
"$ref": "#/$defs/RedemptionResourceEnum"
}
},
"required": [
"code",
"discount_type",
"name"
]
}
],
"$defs": {
"CouponDurationEnum": {
"type": "string",
"enum": [
"forever",
"single_use",
"temporal",
"billing_periods"
]
},
"CouponPricing": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "3-letter ISO 4217 currency code."
},
"discount": {
"type": "number",
"format": "float",
"description": "The fixed discount (in dollars) for the corresponding currency."
}
}
},
"CouponRedeemByIntervalUnitEnum": {
"type": "string",
"title": "Redeem by interval unit",
"description": "Unit of the relative redemption window. Bulk coupons only.",
"enum": [
"day",
"week",
"month",
"year"
]
},
"CouponTypeEnum": {
"type": "string",
"enum": [
"bulk",
"single_code"
]
},
"CouponUpdate": {
"type": "object",
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "The internal name for the coupon."
},
"max_redemptions": {
"type": "integer",
"title": "Max redemptions",
"description": "A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions."
},
"max_redemptions_per_account": {
"type": "integer",
"title": "Max redemptions per account",
"description": "Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to `1` if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign."
},
"hosted_description": {
"type": "string",
"title": "Hosted Payment Pages description",
"description": "This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page."
},
"invoice_description": {
"type": "string",
"title": "Invoice description",
"description": "Description of the coupon on the invoice.",
"maxLength": 255
},
"redeem_by_date": {
"type": "string",
"title": "Redeem by",
"description": "The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time. Mutually exclusive with redeem_by_interval_unit/redeem_by_interval_amount."
},
"redeem_by_interval_unit": {
"title": "Redeem by interval unit",
"description": "Unit of the relative redemption window. Must be paired with redeem_by_interval_amount. Mutually exclusive with redeem_by_date. Bulk coupons only.",
"$ref": "#/$defs/CouponRedeemByIntervalUnitEnum"
},
"redeem_by_interval_amount": {
"type": "integer",
"title": "Redeem by interval amount",
"description": "Quantity of redeem_by_interval_unit. Must be paired with redeem_by_interval_unit.",
"minimum": 1
}
}
},
"DiscountTypeEnum": {
"type": "string",
"enum": [
"fixed",
"free_trial",
"percent"
]
},
"FreeTrialUnitEnum": {
"type": "string",
"enum": [
"day",
"month",
"week",
"billing_period"
]
},
"RedemptionResourceEnum": {
"type": "string",
"enum": [
"account",
"subscription"
]
},
"TemporalUnitEnum": {
"type": "string",
"description": "The temporal unit for the coupon's duration. Used with temporal_amount to define how long the coupon applies. When temporal_unit is billing_period, the coupon applies for temporal_amount complete billing cycles rather than a fixed calendar duration. billing_period requires redemption_resource=subscription.",
"enum": [
"day",
"month",
"week",
"year",
"billing_period"
]
}
}
}
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/recurly-coupon-create"
All schemas
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.