---
updatedAt: 2026-05-12T21:33:18.000Z
agentTools:
  projectIndex: https://developers.intandem.tech/llms.txt
---

# Apply Coupon to Entity

## Overview
Applies a coupon to a specific entity (payment, appointment, or event attendance), granting the associated discount. Available for **Staff tokens**.

## Validation
- The coupon must be active (not expired or disabled).
- The coupon must not have exceeded its `max_redemptions` or `max_redemptions_per_client` limits.
- If the coupon has `valid_services` or `valid_staff` restrictions, the entity must match those restrictions.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Sales",
    "description": "Unified OpenAPI specification for sales domain",
    "version": "3.0",
    "x-generated": {
      "sourceFiles": [
        "payment_plans.json",
        "payments.json",
        "legacy_v1_sales.json",
        "payment_gateway.json",
        "legacy_v2_settings_services.json",
        "legacy_v2_settings_categories.json",
        "client_cards.json",
        "client_payment_cards.json",
        "sales_reports.json",
        "creditNote.json",
        "estimates.json",
        "coupons.json",
        "invoice.json",
        "coupon.json"
      ],
      "pathNormalizations": [
        {
          "file": "payments.json",
          "basePath": "/business/payments",
          "transformations": [
            {
              "original": "/v1/card_requests",
              "normalized": "/business/payments/v1/card_requests",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/card_requests/{client_uid}",
              "normalized": "/business/payments/v1/card_requests/{client_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/cards/{uid}",
              "normalized": "/business/payments/v1/cards/{uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/carts",
              "normalized": "/business/payments/v1/carts",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/carts/{uid}",
              "normalized": "/business/payments/v1/carts/{uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/carts/{uid}/cancel",
              "normalized": "/business/payments/v1/carts/{uid}/cancel",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/carts/{uid}/cart_completed",
              "normalized": "/business/payments/v1/carts/{uid}/cart_completed",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/client_packages/{uid}",
              "normalized": "/business/payments/v1/client_packages/{uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/deposits",
              "normalized": "/business/payments/v1/deposits",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/deposits/{uid}",
              "normalized": "/business/payments/v1/deposits/{uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/estimates",
              "normalized": "/business/payments/v1/estimates",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/estimates/{estimate_uid}",
              "normalized": "/business/payments/v1/estimates/{estimate_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/invoices",
              "normalized": "/business/payments/v1/invoices",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/invoices/{invoice_uid}",
              "normalized": "/business/payments/v1/invoices/{invoice_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/invoices/{invoice_uid}/cancel",
              "normalized": "/business/payments/v1/invoices/{invoice_uid}/cancel",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/packages/reorder",
              "normalized": "/business/payments/v1/packages/reorder",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/payment_requests",
              "normalized": "/business/payments/v1/payment_requests",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/payment_requests/{payment_request_uid}/send_link",
              "normalized": "/business/payments/v1/payment_requests/{payment_request_uid}/send_link",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/payment_requests/{payment_request_uid}",
              "normalized": "/business/payments/v1/payment_requests/{payment_request_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/payments",
              "normalized": "/business/payments/v1/payments",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/payments/{payment_uid}",
              "normalized": "/business/payments/v1/payments/{payment_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/payouts",
              "normalized": "/business/payments/v1/payouts",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/payouts/{provider_payout_id}",
              "normalized": "/business/payments/v1/payouts/{provider_payout_id}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/product_orders",
              "normalized": "/business/payments/v1/product_orders",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/product_orders/{product_order_uid}",
              "normalized": "/business/payments/v1/product_orders/{product_order_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/products",
              "normalized": "/business/payments/v1/products",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/products/{product_uid}",
              "normalized": "/business/payments/v1/products/{product_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/refunds",
              "normalized": "/business/payments/v1/refunds",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/scheduled_payments_rules",
              "normalized": "/business/payments/v1/scheduled_payments_rules",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/scheduled_payments_rules/{uid}/cancel",
              "normalized": "/business/payments/v1/scheduled_payments_rules/{uid}/cancel",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/scheduled_payments_rules/{uid}",
              "normalized": "/business/payments/v1/scheduled_payments_rules/{uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/tax_bulk",
              "normalized": "/business/payments/v1/tax_bulk",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/tax_bulk/apply_defaults",
              "normalized": "/business/payments/v1/tax_bulk/apply_defaults",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/taxes",
              "normalized": "/business/payments/v1/taxes",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/taxes/{tax_uid}",
              "normalized": "/business/payments/v1/taxes/{tax_uid}",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/transactions",
              "normalized": "/business/payments/v1/transactions",
              "basePath": "/business/payments"
            },
            {
              "original": "/v1/transactions/{provider_transaction_id}",
              "normalized": "/business/payments/v1/transactions/{provider_transaction_id}",
              "basePath": "/business/payments"
            }
          ]
        },
        {
          "file": "legacy_v1_sales.json",
          "basePath": "/platform/v1",
          "transformations": [
            {
              "original": "/leadgen",
              "normalized": "/platform/v1/leadgen",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payments",
              "normalized": "/platform/v1/payments",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payments/{payment_uid}",
              "normalized": "/platform/v1/payments/{payment_uid}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payments/{payment_uid}/match",
              "normalized": "/platform/v1/payments/{payment_uid}/match",
              "basePath": "/platform/v1"
            },
            {
              "original": "/invoices",
              "normalized": "/platform/v1/invoices",
              "basePath": "/platform/v1"
            },
            {
              "original": "/invoices/{invoice_id}",
              "normalized": "/platform/v1/invoices/{invoice_id}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/cards/sync_card",
              "normalized": "/platform/v1/payment/cards/sync_card",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/cards/{card_id}",
              "normalized": "/platform/v1/payment/cards/{card_id}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/checkout/",
              "normalized": "/platform/v1/payment/checkout/",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/checkout/{url_key}",
              "normalized": "/platform/v1/payment/checkout/{url_key}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/client_packages",
              "normalized": "/platform/v1/payment/client_packages",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/client_packages/cancel_redemption",
              "normalized": "/platform/v1/payment/client_packages/cancel_redemption",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/client_packages/update_usage",
              "normalized": "/platform/v1/payment/client_packages/update_usage",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/packages",
              "normalized": "/platform/v1/payment/packages",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/packages/{package_id}",
              "normalized": "/platform/v1/payment/packages/{package_id}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/settings",
              "normalized": "/platform/v1/payment/settings",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment/settings/update_default_currency",
              "normalized": "/platform/v1/payment/settings/update_default_currency",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment_statuses/{id}/apply_coupon",
              "normalized": "/platform/v1/payment_statuses/{id}/apply_coupon",
              "basePath": "/platform/v1"
            },
            {
              "original": "/payment_statuses/{id}/validate_coupon",
              "normalized": "/platform/v1/payment_statuses/{id}/validate_coupon",
              "basePath": "/platform/v1"
            },
            {
              "original": "/services",
              "normalized": "/platform/v1/services",
              "basePath": "/platform/v1"
            },
            {
              "original": "/services/availability",
              "normalized": "/platform/v1/services/availability",
              "basePath": "/platform/v1"
            },
            {
              "original": "/services/{service_uid}",
              "normalized": "/platform/v1/services/{service_uid}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/services/{service_uid}/availability",
              "normalized": "/platform/v1/services/{service_uid}/availability",
              "basePath": "/platform/v1"
            }
          ]
        },
        {
          "file": "estimates.json",
          "basePath": "/platform/v1",
          "transformations": [
            {
              "original": "/estimates",
              "normalized": "/platform/v1/estimates",
              "basePath": "/platform/v1"
            }
          ]
        }
      ],
      "pathConflicts": [],
      "componentConflicts": [
        {
          "type": "schema",
          "name": "ErrorResponse",
          "resolution": "Renamed to ErrorResponse_client_cards",
          "files": [
            "merged",
            "client_cards.json"
          ]
        }
      ],
      "totalPaths": 86,
      "totalComponents": 11
    }
  },
  "servers": [
    {
      "url": "https://api.vcita.biz",
      "description": "Unified API Gateway server"
    }
  ],
  "paths": {
    "/v2/coupons/{uid}/apply": {
      "post": {
        "description": "## Overview\nApplies a coupon to a specific entity (payment, appointment, or event attendance), granting the associated discount. Available for **Staff tokens**.\n\n## Validation\n- The coupon must be active (not expired or disabled).\n- The coupon must not have exceeded its `max_redemptions` or `max_redemptions_per_client` limits.\n- If the coupon has `valid_services` or `valid_staff` restrictions, the entity must match those restrictions.",
        "parameters": [
          {
            "description": "The unique identifier of the coupon to apply.",
            "in": "path",
            "name": "uid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "coupon_redemption": {
                      "id": "crd_xyz789",
                      "code": "SUMMER20",
                      "coupon_type": "percent",
                      "discount_h": "20%",
                      "amount": 20,
                      "name": "Summer Sale",
                      "redeemed_at": "2026-02-08T12:00:00Z"
                    }
                  },
                  "success": true
                }
              }
            }
          },
          "422": {
            "description": "Failure",
            "content": {
              "application/json": {
                "example": {
                  "errors": [
                    {
                      "code": "invalid",
                      "message": "Coupon has reached its maximum number of redemptions"
                    }
                  ],
                  "success": false
                }
              }
            }
          }
        },
        "summary": "Apply Coupon to Entity",
        "tags": [
          "Coupons"
        ],
        "x-amazon-apigateway-auth": {
          "type": "NONE"
        },
        "x-amazon-apigateway-integration": {
          "httpMethod": "POST",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "type": "http_proxy",
          "uri": "https:///v2/coupons/{uid}/apply"
        },
        "x-auth-type": "Application & Application User",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "entity_type": {
                    "description": "The type of entity to apply the coupon to. Possible values: `payment`, `appointment`, `event_attendance`.",
                    "type": "string"
                  },
                  "entity_id": {
                    "description": "The UID of the entity to apply the coupon to.",
                    "type": "string"
                  }
                },
                "required": [
                  "entity_type",
                  "entity_id"
                ],
                "type": "object"
              }
            }
          }
        },
        "security": [
          {
            "Bearer": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Provide a valid bearer token in the Authorization header. Example: 'Authorization: Bearer {app_token}'"
      }
    }
  }
}
```