Recurly · Schema
Coupon
SubscriptionBillingPaymentsRecurring RevenueInvoicingDunningRevenue RecognitionChurnMCPShopifyWebhook
Properties
| Name | Type | Description |
|---|---|---|
| id | string | |
| object | string | |
| code | string | The code the customer enters to redeem the coupon. |
| name | string | The internal name for the coupon. |
| state | object | Indicates if the coupon is redeemable, and if it is not, why. |
| 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 |
| unique_coupon_codes_count | integer | When this number reaches `max_redemptions` the coupon will no longer be redeemable. |
| unique_code_template | string | On a bulk coupon, the template from which unique coupon codes are generated. |
| unique_coupon_code | object | Will be populated when the Coupon being returned is a `UniqueCouponCode`. |
| duration | object | - "single_use" coupons applies to the first invoice only. - "temporal" coupons will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes. |
| 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 |
| 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. |
| free_trial_amount | integer | Sets the duration of time the `free_trial_unit` is for. |
| 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 | The coupon is valid for all items if true. If false then `items` will list the applicable items. |
| applies_to_non_plan_charges | boolean | The coupon is valid for one-time, non-plan charges if true. |
| plans | array | A list of plans for which this coupon applies. This will be `null` if `applies_to_all_plans=true`. |
| items | array | A list of items for which this coupon applies. This will be `null` if `applies_to_all_items=true`. |
| redemption_resource | object | Whether the discount is for all eligible charges on the account, or only a specific subscription. |
| discount | object | |
| 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. |
| hosted_page_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 | 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. Null for bulk coupons configured with a relative redeem-by interval (see r |
| redeem_by_interval_unit | object | For a bulk coupon with a relative redeem-by, the unit of the interval after which each generated unique code expires. Null unless the coupon uses a relative redeem-by. |
| redeem_by_interval_amount | integer | For a bulk coupon with a relative redeem-by, the number of redeem_by_interval_unit intervals after a code's generation that it remains redeemable. Null unless the coupon uses a relative redeem-by. |
| created_at | string | |
| updated_at | string | |
| expired_at | string | The date and time the coupon was expired early or reached its `max_redemptions`. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/recurly/json-schema/recurly-coupon-schema.json",
"title": "Coupon",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/recurly-coupon-api-openapi.yml#/components/schemas/Coupon",
"type": "object",
"properties": {
"id": {
"type": "string",
"title": "Coupon ID",
"readOnly": true
},
"object": {
"type": "string",
"title": "Object type",
"readOnly": true
},
"code": {
"type": "string",
"title": "Coupon code",
"description": "The code the customer enters to redeem the coupon."
},
"name": {
"type": "string",
"title": "Name",
"description": "The internal name for the coupon."
},
"state": {
"title": "State",
"description": "Indicates if the coupon is redeemable, and if it is not, why.",
"$ref": "#/$defs/CouponStateEnum"
},
"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."
},
"unique_coupon_codes_count": {
"type": "integer",
"title": "Unique coupon codes count",
"description": "When this number reaches `max_redemptions` the coupon will no longer be redeemable.",
"readOnly": true
},
"unique_code_template": {
"type": "string",
"title": "Unique code template",
"description": "On a bulk coupon, the template from which unique coupon codes are generated."
},
"unique_coupon_code": {
"allOf": [
{
"$ref": "#/$defs/UniqueCouponCode"
}
],
"type": "object",
"description": "Will be populated when the Coupon being returned is a `UniqueCouponCode`."
},
"duration": {
"title": "Duration",
"description": "- \"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",
"$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`.",
"$ref": "#/$defs/TemporalUnitEnum"
},
"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.",
"$ref": "#/$defs/FreeTrialUnitEnum"
},
"free_trial_amount": {
"type": "integer",
"title": "Free trial amount",
"description": "Sets the duration of time the `free_trial_unit` is for.",
"minimum": 1,
"maximum": 9999
},
"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": "The coupon is valid for all items if true. If false then `items`\nwill list the applicable items.\n",
"default": false
},
"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
},
"plans": {
"type": "array",
"title": "Plans",
"description": "A list of plans for which this coupon applies. This will be `null` if `applies_to_all_plans=true`.",
"items": {
"$ref": "#/$defs/PlanMini"
}
},
"items": {
"type": "array",
"title": "Items",
"description": "A list of items for which this coupon applies. This will be\n`null` if `applies_to_all_items=true`.\n",
"items": {
"$ref": "#/$defs/ItemMini"
}
},
"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"
},
"discount": {
"$ref": "#/$defs/CouponDiscount"
},
"coupon_type": {
"title": "Coupon type (TODO: implement coupon generation)",
"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"
},
"hosted_page_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": {
"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. Null for bulk coupons configured with a relative redeem-by interval (see redeem_by_interval_unit and redeem_by_interval_amount).",
"format": "date-time"
},
"redeem_by_interval_unit": {
"title": "Redeem by interval unit",
"description": "For a bulk coupon with a relative redeem-by, the unit of the interval after which each generated unique code expires. Null unless the coupon uses a relative redeem-by.",
"readOnly": true,
"$ref": "#/$defs/CouponRedeemByIntervalUnitEnum"
},
"redeem_by_interval_amount": {
"type": "integer",
"title": "Redeem by interval amount",
"description": "For a bulk coupon with a relative redeem-by, the number of redeem_by_interval_unit intervals after a code's generation that it remains redeemable. Null unless the coupon uses a relative redeem-by.",
"readOnly": true
},
"created_at": {
"type": "string",
"title": "Created at",
"format": "date-time",
"readOnly": true
},
"updated_at": {
"type": "string",
"title": "Last updated at",
"format": "date-time",
"readOnly": true
},
"expired_at": {
"type": "string",
"title": "Expired at",
"description": "The date and time the coupon was expired early or reached its `max_redemptions`.",
"format": "date-time"
}
},
"$defs": {
"ActiveStateEnum": {
"type": "string",
"enum": [
"active",
"inactive"
]
},
"CouponCodeStateEnum": {
"type": "string",
"enum": [
"expired",
"inactive",
"maxed_out",
"redeemable"
]
},
"CouponDiscount": {
"type": "object",
"description": "Details of the discount a coupon applies. Will contain a `type`\nproperty and one of the following properties: `percent`, `fixed`, `trial`.\n",
"properties": {
"type": {
"$ref": "#/$defs/DiscountTypeEnum"
},
"percent": {
"description": "This is only present when `type=percent`.",
"type": "integer"
},
"currencies": {
"type": "array",
"description": "This is only present when `type=fixed`.",
"items": {
"$ref": "#/$defs/CouponDiscountPricing"
}
},
"trial": {
"type": "object",
"x-class-name": "CouponDiscountTrial",
"description": "This is only present when `type=free_trial`.",
"properties": {
"unit": {
"title": "Trial unit",
"description": "Temporal unit of the free trial. When `billing_period`, `length` represents the number of billing cycles.",
"$ref": "#/$defs/FreeTrialUnitEnum"
},
"length": {
"type": "integer",
"title": "Trial length",
"description": "Trial length measured in the units specified by the sibling `unit` property"
}
}
}
}
},
"CouponDiscountPricing": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"title": "Currency",
"description": "3-letter ISO 4217 currency code.",
"maxLength": 3
},
"amount": {
"type": "number",
"format": "float",
"title": "Discount Amount",
"description": "Value of the fixed discount that this coupon applies."
}
}
},
"CouponDurationEnum": {
"type": "string",
"enum": [
"forever",
"single_use",
"temporal",
"billing_periods"
]
},
"CouponRedeemByIntervalUnitEnum": {
"type": "string",
"title": "Redeem by interval unit",
"description": "Unit of the relative redemption window. Bulk coupons only.",
"enum": [
"day",
"week",
"month",
"year"
]
},
"CouponStateEnum": {
"type": "string",
"enum": [
"expired",
"maxed_out",
"redeemable"
]
},
"CouponTypeEnum": {
"type": "string",
"enum": [
"bulk",
"single_code"
]
},
"DiscountTypeEnum": {
"type": "string",
"enum": [
"fixed",
"free_trial",
"percent"
]
},
"FreeTrialUnitEnum": {
"type": "string",
"enum": [
"day",
"month",
"week",
"billing_period"
]
},
"ItemMini": {
"type": "object",
"title": "Item mini details",
"description": "Just the important parts.",
"properties": {
"id": {
"type": "string",
"title": "Item ID",
"maxLength": 13,
"readOnly": true
},
"object": {
"type": "string",
"title": "Object type",
"readOnly": true
},
"code": {
"type": "string",
"title": "Item code",
"description": "Unique code to identify the item.",
"pattern": "/^[a-z0-9_+-]+$/",
"maxLength": 50
},
"state": {
"title": "State",
"description": "The current state of the item.",
"readOnly": true,
"$ref": "#/$defs/ActiveStateEnum"
},
"name": {
"type": "string",
"title": "Name",
"description": "This name describes your item and will appear on the invoice when it's purchased on a one time basis.",
"maxLength": 255
},
"description": {
"type": "string",
"title": "Description",
"description": "Optional, description."
}
}
},
"PlanCode": {
"type": "string",
"title": "Plan code",
"description": "Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.",
"pattern": "/^[a-z0-9_+-]+$/",
"maxLength": 50
},
"PlanMini": {
"type": "object",
"title": "Plan mini details",
"description": "Just the important parts.",
"properties": {
"id": {
"type": "string",
"title": "Plan ID",
"maxLength": 13,
"readOnly": true
},
"object": {
"type": "string",
"title": "Object type",
"readOnly": true
},
"code": {
"$ref": "#/$defs/PlanCode"
},
"name": {
"$ref": "#/$defs/PlanName"
}
}
},
"PlanName": {
"type": "string",
"title": "Name",
"description": "This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.",
"maxLength": 255
},
"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"
]
},
"UniqueCouponCode": {
"type": "object",
"description": "A unique coupon code for a bulk coupon.",
"properties": {
"id": {
"type": "string",
"title": "Unique Coupon Code ID",
"readOnly": true
},
"object": {
"type": "string",
"title": "Object type",
"readOnly": true
},
"code": {
"type": "string",
"title": "Coupon code",
"description": "The code the customer enters to redeem the coupon."
},
"state": {
"title": "State",
"description": "Indicates if the unique coupon code is redeemable or why not.",
"$ref": "#/$defs/CouponCodeStateEnum"
},
"bulk_coupon_id": {
"type": "string",
"title": "Bulk Coupon ID",
"description": "The Coupon ID of the parent Bulk Coupon",
"readOnly": true
},
"bulk_coupon_code": {
"type": "string",
"title": "Bulk Coupon code",
"description": "The Coupon code of the parent Bulk Coupon"
},
"created_at": {
"type": "string",
"title": "Created at",
"format": "date-time",
"readOnly": true
},
"updated_at": {
"type": "string",
"title": "Updated at",
"format": "date-time",
"readOnly": true
},
"redeemed_at": {
"type": "string",
"title": "Redeemed at",
"description": "The date and time the unique coupon code was redeemed.",
"format": "date-time",
"readOnly": true
},
"expired_at": {
"type": "string",
"title": "Expired at",
"description": "The date and time the coupon was expired early or reached its `max_redemptions`.",
"format": "date-time"
},
"redeem_by_date": {
"type": "string",
"title": "Redeem by",
"description": "Absolute expiry computed and stored at code-generation time. Set only for Window (relative redeem-by) coupons. Null for Anytime coupons and Specific Date coupons — those resolve expiry from the parent coupon's redeem_by at redemption time, not at code-generation time.",
"format": "date-time",
"readOnly": true
}
}
}
}
}
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"
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.