Discounts & Coupons

A discount rule (`disc_*`) reduces what a customer pays. It is either `automatic` (applies on its own whenever a matching product, price, or order is bought) or a `code` the customer enters at checkout. A rule targets the whole `order`, specific `products`, or specific `prices`, and carries a `duration` (`once`, `n_charges`, `until_date`, `forever`) that controls how long it keeps reducing a subscription's charges once attached. Value types: `percent` (`value` in basis points - 2500 = 25%, max 10000), `amount` (`value` agorot to subtract, needs `currency`), or `override` (`value` agorot target unit price, needs `currency` and an optional `value_tax_mode`). Codes are normalized to UPPERCASE and are intentionally NOT unique - several rules can share one coupon code to reduce different products/prices differently. Apply a code at checkout via `coupon_codes` on Create Checkout Session or the public apply-discount endpoint; attach rules to an API-created subscription via the subscription's `discounts` field. Once attached to a subscription a rule becomes an applied_discount (`di_*`) with status `active`, `completed`, or `canceled`.

Use cases: Run a launch coupon, give a percentage off a specific plan for the first N renewals, set a fixed promotional price, or auto-apply an order-wide discount during a sale.

POST/v1/discounts

Create a discount rule. Fires discount.created.

Body Parameters

Name	Type		Description
`name`	string	required	Internal label (1-255 chars).
`redemption`	string	required	"automatic" (applies on its own when matching items are bought) or "code" (customer enters a code).
`code`	string		Required when redemption is "code"; must be omitted for automatic rules. Normalized to UPPERCASE, charset [A-Z0-9_-]{1,64}. Not unique - several rules can share one code.
`target_type`	string	required	"order" (whole order/cart, apportioned across lines), "products", or "prices".
`targets`	array		Required for products/prices target types: an array of product (prod_) or price (price_) visibleIds the rule reduces. An unknown id is rejected with 400 target_not_found.
`value_type`	string	required	"percent" (value in basis points, max 10000), "amount" (value agorot to subtract), or "override" (value agorot target unit price).
`value`	integer	required	Non-negative integer, interpreted per value_type.
`value_tax_mode`	string		Override rules only: "inclusive" (default) or "exclusive" - whether the override price is quoted incl. or excl. VAT.
`currency`	string		Required for amount/override (e.g. "ils"); must be omitted for percent.
`duration`	string	required	"once", "n_charges", "until_date", or "forever" - how long the rule keeps reducing once attached to a subscription.
`duration_charges`	integer		Required when duration is n_charges: number of charges the discount applies to.
`duration_until`	string		Required when duration is until_date: ISO 8601 datetime the discount stops applying.
`active_from`	string		Optional ISO 8601 start of the eligibility window.
`active_until`	string		Optional ISO 8601 end of the eligibility window.
`max_redemptions`	integer		Optional global cap on total redemptions.
`max_redemptions_per_customer`	integer		Optional per-customer redemption cap.
`active`	boolean		Defaults to true.
`metadata`	object		Set of key-value pairs you can attach to the object for your own use. Returned as-is on retrieval.

Request

curl -X POST "https://api.ching.co.il/ching/v1/discounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example_name",
  "redemption": "example_redemption",
  "code": "example_code",
  "target_type": "example_target_type",
  "targets": [],
  "value_type": "example_value_type",
  "value": 0,
  "value_tax_mode": "example_value_tax_mode",
  "currency": "example_currency",
  "duration": "example_duration",
  "duration_charges": 0,
  "duration_until": "example_duration_until",
  "active_from": "example_active_from",
  "active_until": "example_active_until",
  "max_redemptions": 0,
  "max_redemptions_per_customer": 0,
  "active": true,
  "metadata": {}
}'

Response

{
  "success": true,
  "data": {
    "id": "disc_8kQ2vN1pLm4z",
    "object": "discount",
    "name": "Launch 25%",
    "redemption": "code",
    "code": "LAUNCH25",
    "target_type": "prices",
    "targets": [
      "price_QA8qF3B3VIqE"
    ],
    "value_type": "percent",
    "value": 2500,
    "value_tax_mode": null,
    "currency": null,
    "duration": "n_charges",
    "duration_charges": 3,
    "duration_until": null,
    "active_from": null,
    "active_until": null,
    "max_redemptions": 500,
    "max_redemptions_per_customer": 1,
    "times_redeemed": 12,
    "active": true,
    "archived": false,
    "metadata": {},
    "livemode": false,
    "created": "2026-06-07T08:00:00.000Z"
  }
}

GET/v1/discounts

List up to 100 most-recent discount rules, newest first.

Request

curl -X GET "https://api.ching.co.il/ching/v1/discounts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": [
    {
      "id": "disc_8kQ2vN1pLm4z",
      "object": "discount",
      "name": "Launch 25%",
      "redemption": "code",
      "code": "LAUNCH25",
      "target_type": "prices",
      "targets": [
        "price_QA8qF3B3VIqE"
      ],
      "value_type": "percent",
      "value": 2500,
      "value_tax_mode": null,
      "currency": null,
      "duration": "n_charges",
      "duration_charges": 3,
      "duration_until": null,
      "active_from": null,
      "active_until": null,
      "max_redemptions": 500,
      "max_redemptions_per_customer": 1,
      "times_redeemed": 12,
      "active": true,
      "archived": false,
      "metadata": {},
      "livemode": false,
      "created": "2026-06-07T08:00:00.000Z"
    }
  ]
}

GET/v1/discounts/:id

Retrieve a discount rule, including its resolved product/price targets.

Path Parameters

Name	Type		Description
`id`	string	required	The discount id.

Request

curl -X GET "https://api.ching.co.il/ching/v1/discounts/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "disc_8kQ2vN1pLm4z",
    "object": "discount",
    "name": "Launch 25%",
    "redemption": "code",
    "code": "LAUNCH25",
    "target_type": "prices",
    "targets": [
      "price_QA8qF3B3VIqE"
    ],
    "value_type": "percent",
    "value": 2500,
    "value_tax_mode": null,
    "currency": null,
    "duration": "n_charges",
    "duration_charges": 3,
    "duration_until": null,
    "active_from": null,
    "active_until": null,
    "max_redemptions": 500,
    "max_redemptions_per_customer": 1,
    "times_redeemed": 12,
    "active": true,
    "archived": false,
    "metadata": {},
    "livemode": false,
    "created": "2026-06-07T08:00:00.000Z"
  }
}

POST/v1/discounts/:id

Update the mutable fields of a rule. value, value_type, target_type, and duration are frozen once the rule exists so already-applied discounts keep their terms. Fires discount.updated.

Path Parameters

Name	Type		Description
`id`	string	required	The discount id.

Body Parameters

Name	Type	Description
`name`	string	1-255 chars.
`active`	boolean	Enable or disable the rule.
`active_from`	string	ISO 8601 datetime, nullable.
`active_until`	string	ISO 8601 datetime, nullable.
`max_redemptions`	integer	Nullable global cap.
`max_redemptions_per_customer`	integer	Nullable per-customer cap.
`metadata`	object	Set of key-value pairs you can attach to the object for your own use. Returned as-is on retrieval.

Request

curl -X POST "https://api.ching.co.il/ching/v1/discounts/:id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "example_name",
  "active": true,
  "active_from": "example_active_from",
  "active_until": "example_active_until",
  "max_redemptions": 0,
  "max_redemptions_per_customer": 0,
  "metadata": {}
}'

Response

{
  "success": true,
  "data": {
    "id": "disc_8kQ2vN1pLm4z",
    "object": "discount",
    "name": "Launch 25%",
    "redemption": "code",
    "code": "LAUNCH25",
    "target_type": "prices",
    "targets": [
      "price_QA8qF3B3VIqE"
    ],
    "value_type": "percent",
    "value": 2500,
    "value_tax_mode": null,
    "currency": null,
    "duration": "n_charges",
    "duration_charges": 3,
    "duration_until": null,
    "active_from": null,
    "active_until": null,
    "max_redemptions": 500,
    "max_redemptions_per_customer": 1,
    "times_redeemed": 12,
    "active": true,
    "archived": false,
    "metadata": {},
    "livemode": false,
    "created": "2026-06-07T08:00:00.000Z"
  }
}

POST/v1/discounts/:id/targets

Replace the full set of product/price targets for a rule. The ids must match the rule's target_type (products → prod_*, prices → price_*). Rejected for order-type rules with 400 targets_not_supported. Fires discount.updated.

Path Parameters

Name	Type		Description
`id`	string	required	The discount id.

Body Parameters

Name	Type		Description
`targets`	array	required	The complete set of product or price visibleIds the rule should target (replaces any existing targets).

Request

curl -X POST "https://api.ching.co.il/ching/v1/discounts/:id/targets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "targets": []
}'

Response

{
  "success": true,
  "data": {
    "id": "disc_8kQ2vN1pLm4z",
    "object": "discount",
    "name": "Launch 25%",
    "redemption": "code",
    "code": "LAUNCH25",
    "target_type": "prices",
    "targets": [
      "price_QA8qF3B3VIqE"
    ],
    "value_type": "percent",
    "value": 2500,
    "value_tax_mode": null,
    "currency": null,
    "duration": "n_charges",
    "duration_charges": 3,
    "duration_until": null,
    "active_from": null,
    "active_until": null,
    "max_redemptions": 500,
    "max_redemptions_per_customer": 1,
    "times_redeemed": 12,
    "active": true,
    "archived": false,
    "metadata": {},
    "livemode": false,
    "created": "2026-06-07T08:00:00.000Z"
  }
}

POST/v1/discounts/:id/archive

Archive (soft-delete) a rule. An archived rule never matches at checkout or renewal, but discounts already attached to subscriptions run out their own duration. Idempotent. Fires discount.deleted.

Path Parameters

Name	Type		Description
`id`	string	required	The discount id.

Request

curl -X POST "https://api.ching.co.il/ching/v1/discounts/:id/archive" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "id": "disc_8kQ2vN1pLm4z",
    "object": "discount",
    "name": "Launch 25%",
    "redemption": "code",
    "code": "LAUNCH25",
    "target_type": "prices",
    "targets": [
      "price_QA8qF3B3VIqE"
    ],
    "value_type": "percent",
    "value": 2500,
    "value_tax_mode": null,
    "currency": null,
    "duration": "n_charges",
    "duration_charges": 3,
    "duration_until": null,
    "active_from": null,
    "active_until": null,
    "max_redemptions": 500,
    "max_redemptions_per_customer": 1,
    "times_redeemed": 12,
    "active": false,
    "archived": true,
    "metadata": {},
    "livemode": false,
    "created": "2026-06-07T08:00:00.000Z"
  }
}

GET/v1/discounts/:id/redemptions

Read-only detail for a rule: the redemption events (who redeemed, on which charge, how much was saved) and the per-subscription applied-discount status (charges applied vs the rule's duration_charges). Free-plan/trial redemptions carry a null charge and amount.

Path Parameters

Name	Type		Description
`id`	string	required	The discount id.

Request

curl -X GET "https://api.ching.co.il/ching/v1/discounts/:id/redemptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "success": true,
  "data": {
    "redemptions": [
      {
        "id": 41,
        "object": "discount_redemption",
        "customer": "cus_V8ltq1pK_MWH",
        "customer_name": "Dana Levi",
        "customer_email": "dana@example.com",
        "subscription": "sub_hXUPYOnvxp-q",
        "charge": "ch_9mTPfRSDmEOU",
        "charge_amount": 4990,
        "currency": "ils",
        "amount_saved": 1248,
        "created": "2026-06-08T10:00:00.000Z"
      }
    ],
    "applied_discounts": [
      {
        "id": "di_3pQ7rT2wXc9k",
        "object": "applied_discount",
        "subscription": "sub_hXUPYOnvxp-q",
        "status": "active",
        "charges_applied": 1,
        "duration_charges": 3,
        "started_at": "2026-06-08T10:00:00.000Z",
        "ends_at": null
      }
    ]
  }
}