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`.
View JSON Schema on GitHub

JSON Schema

recurly-coupon-schema.json Raw ↑
{
  "$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.
All 92 tools →

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.