Coupon response/update payload

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/emporix/main/json-schema/emporix-base-coupon-schema.json",
  "title": "Coupon response/update payload",
  "description": "Coupons describe voucher alike commerce capabilities, e.g. 10% off winter accessories.",
  "x-generated": "2026-10-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/emporix-coupon-openapi.yml#/components/schemas/base-coupon",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Coupon name."
    },
    "description": {
      "type": "string",
      "description": "Coupon description."
    },
    "discountType": {
      "enum": [
        "PERCENT",
        "ABSOLUTE",
        "FREE_SHIPPING"
      ],
      "description": "'PERCENT' for relative values, 'ABSOLUTE' for float values, referring to a specific currency, 'FREE_SHIPPING' for reducing the shipping cost to 0.",
      "type": "string"
    },
    "discountPercentage": {
      "type": "number",
      "description": "A discount percentage within the range [0.00, 100.00]. Must be specified only if type is 'PERCENT'.",
      "minimum": 0,
      "maximum": 100
    },
    "discountAbsolute": {
      "type": "object",
      "description": "Must be specified only if type is 'ABSOLUTE'. Defines the amount that should be substracted from the cart subtotal.",
      "properties": {
        "amount": {
          "type": "number",
          "description": "Total amount in the specified currency."
        },
        "currency": {
          "type": "string",
          "description": "ISO 4217 currency code, e.g.: USD, EUR, CHF."
        }
      }
    },
    "allowAnonymous": {
      "type": "boolean",
      "description": "Specifies if the coupon can be redeemed by anonymous user. If set to false, only logged-in customers can redeem it.",
      "default": false
    },
    "maxRedemptions": {
      "type": "number",
      "description": "Maximum number of redemptions; -1  designates 'unlimited' (seller-only).",
      "default": -1
    },
    "maxRedemptionsPerCustomer": {
      "type": "number",
      "description": "Maximum number of redemptions per customer; -1 designates 'unlimited'. Cannot be specified for coupons which can be redeemed by anonymous users.",
      "default": -1
    },
    "discountCalculationType": {
      "type": "string",
      "enum": [
        "TOTAL",
        "SUBTOTAL"
      ],
      "description": "Determines whether the coupon is applied to the total or subtotal value of the order.",
      "default": "SUBTOTAL"
    },
    "categoryRestricted": {
      "$ref": "#/$defs/categoryRestricted"
    },
    "segmentRestricted": {
      "$ref": "#/$defs/segmentRestricted"
    },
    "vendorRestricted": {
      "$ref": "#/$defs/vendorRestricted"
    },
    "restrictions": {
      "$ref": "#/$defs/restrictions"
    },
    "issuedTo": {
      "type": "string",
      "description": "The Id of the customer who originally received the coupon (seller-only)."
    },
    "mixins": {
      "type": "object",
      "description": "The field contains mixins values.",
      "additionalProperties": true
    },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "version": {
          "description": "Version of the document. Set to 0 after creating a document. Increments by 1 after every update.",
          "type": "number"
        },
        "mixins": {
          "type": "object",
          "description": "Links to the mixin schemas.",
          "additionalProperties": {
            "type": "string"
          }
        }
      }
    }
  },
  "$defs": {
    "categoryRestricted": {
      "type": "boolean",
      "description": "Defines if the coupon has category restrictions.\n***\nInfo: Cannot be combined together with the segment restrictions.\n",
      "default": false
    },
    "currency-amount": {
      "type": "object",
      "title": "Money amount",
      "description": "Defines an amount in a specific currency.",
      "properties": {
        "amount": {
          "type": "number",
          "default": 0,
          "minimum": 0,
          "description": "Total amount in the specified currency."
        },
        "currency": {
          "type": "string",
          "default": "USD",
          "pattern": "^[A-Z]{3}$",
          "description": "ISO 4217 currency code, e.g.: USD, EUR, CHF."
        }
      }
    },
    "restrictions": {
      "type": "object",
      "description": "Restrictions of the coupon.",
      "properties": {
        "validFor": {
          "type": "array",
          "description": "A list of customer identifiers for whom the coupon can be redeemed. Cannot be specified for coupons which can be redeemed by anonymous users.",
          "items": {
            "type": "string"
          }
        },
        "validFrom": {
          "type": "string",
          "format": "date-time",
          "description": "Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."
        },
        "validUntil": {
          "type": "string",
          "format": "date-time",
          "description": "Must be provided in ISO 8601 format (http://www.iso.org/iso/home/standards/iso8601.htm), e.g. '2015-01-31T23:59:59.999Z'."
        },
        "minOrderValue": {
          "allOf": [
            {
              "$ref": "#/$defs/currency-amount"
            },
            {
              "description": "The minimum order value required to use the coupon. When `vendorRestricted` is `true`, this value is checked against the total of the matching vendor items."
            }
          ]
        },
        "includedCategories": {
          "type": "array",
          "description": "The list of product's categories to which this coupon applies to. Must be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with excludedCategories list.",
          "items": {
            "type": "string"
          }
        },
        "excludedCategories": {
          "type": "array",
          "description": "The list of product's categories to which this coupon does not apply to. Can be defined only if the `categoryRestricted` flag is set to true. Must be disjoint with includedCategories list.",
          "items": {
            "type": "string"
          }
        },
        "segments": {
          "type": "array",
          "description": "The list of segments to which this coupon applies to. Can be defined only if the `segmentRestricted` flag is set to true.",
          "items": {
            "type": "string"
          }
        },
        "vendors": {
          "type": "array",
          "description": "The list of vendor identifiers to which this coupon applies. Must be provided when `vendorRestricted` is `true`, and must be empty when `vendorRestricted` is `false`.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "segmentRestricted": {
      "type": "boolean",
      "description": "Defines if the coupon has segment restrictions. If the value is set to `true`, the `restrictions.segments` must be provided.\n***\nInfo: Cannot be combined neither with the category restrictions nor with customers restrictions.\n",
      "default": false
    },
    "vendorRestricted": {
      "type": "boolean",
      "description": "Defines if the coupon applies only to products from specific vendors. If the value is `true`, `restrictions.vendors` must be provided.\nA vendor restriction can be combined with other restriction types.\n",
      "default": false
    }
  }
}