Manage cart rules and voucher codes
ps_manage_cart_rules
Creates discount codes, including batches of single-use codes, and switches them on or off. New codes start switched off.
TellMyShop Free: No. This tool is only in TellMyShop Pro. TellMyShop Free has only ready reports that read your store.
Ask Claude
„Create code WELCOME10: 10% off orders over 200 PLN, valid until the end of the year, once per customer.”
Example preview
New cart rule "Welcome 10%", code WELCOME10, 10%, min. 200 PLN gross, 2026-10-05 to 2026-12-31, 1 per customer, 1000 uses. Created as INACTIVE: switch it on with set_active after checking.
Technical details
Discount codes (cart rules). action=list (with number of uses) and action=get (details with restrictions). action=create makes one code: percentage, amount or free shipping, minimum cart value, dates, total uses and uses per customer, optional restrictions to categories, products or manufacturers, customer groups, exclusive (doesn't combine with other codes), exclude_discounted, and for percentage discounts apply_to (whole order, selected products or the cheapest product). action=generate makes a series of unique SINGLE-USE codes with a prefix (for example 200 newsletter codes, count up to 500) with the same conditions. action=update changes code, dates, limits, value or name. action=set_active switches a code on or off. action=delete removes a code that was NEVER used in an order (a used code can only be switched off). New codes start INACTIVE unless activate=true. A rule without a code applies to every customer automatically and needs auto_apply=true.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| action | enum: list | get | create | update | set_active | generate | delete | yes | list | get | create | update | set_active | generate | delete. |
| shop_id | integer | no | Shop ID in a multistore installation. Defaults to the shop in the connector address. IDs are listed by ps_get_shop_info. |
| cart_rule_id | integer | when: action=get, update, set_active or delete | get/update/set_active/delete: ID from action=list. |
| name | string | no | create/generate/update: name shown in the customer's cart (for example "Autumn sale -10%"). Max 254 characters. |
| code | string | no | create/update: the code to type in the cart (letters, digits, - and _). |
| auto_apply | boolean | no | create: true = a rule WITHOUT a code, applied automatically to everyone who meets the conditions. Default false. |
| reduction_percent | number | no | discount in % (create/generate/update). Max 100. |
| reduction_amount | number | no | amount discount in the shop currency (create/generate/update). Max 1,000,000. |
| amount_tax_included | boolean | no | create/generate: the amount discount is gross (default). |
| free_shipping | boolean | no | free shipping (create/generate/update). |
| minimum_amount | number | no | minimum gross cart value, 0 = no minimum (create/generate/update). |
| date_from | string (YYYY-MM-DD) | no | valid from (create/generate: default today), YYYY-MM-DD. |
| date_to | string (YYYY-MM-DD) | when: action=create or generate | valid to (create/generate: required), YYYY-MM-DD. |
| quantity | integer | when: action=create | create: total number of uses (required); update: remaining number of uses. Range 0 to 1,000,000. |
| quantity_per_user | integer | no | uses per customer (default 1). Range 1 to 1000. |
| category_ids | array of integer | no | create/generate: the code works only when the cart has a product from these categories (IDs from ps_get_category_tree). Max 50 items. |
| products | array of string | no | create/generate: the code works only with these products. Max 100 items. |
| manufacturer_ids | array of integer | no | create/generate: the code works only with products of these manufacturers. Max 50 items. |
| min_products | integer | no | create/generate: how many such products must be in the cart. Range 1 to 1000. Default 1. |
| apply_to | enum: order | selected_products | cheapest | no | create/generate (percentage discount only): order = whole cart, selected_products = only the restricted products, cheapest = the cheapest product. Default order. |
| exclude_discounted | boolean | no | create/generate/update: the discount skips products that are already discounted. |
| customer_group_ids | array of integer | no | create/generate: only for these customer groups. Max 20 items. |
| exclusive | boolean | no | create/generate: can't be combined with other discount codes. Default false. |
| highlight | boolean | no | create/update: suggest the code in the cart when the customer meets the conditions. |
| partial_use | boolean | no | create/update (amount discount): the unused part of the amount stays as a new code for the customer. |
| description | string | no | create/generate/update: internal description (back office only). Max 254 characters. |
| activate | boolean | no | create/generate: active right away (default no: you switch it on after checking). |
| count | integer | when: action=generate | generate: how many codes (each single use). Range 1 to 500. |
| prefix | string | when: action=generate | generate: code prefix (for example NEWS10 -> NEWS10-7KQ3XW9P). |
| code_length | integer | no | generate: length of the random part of the code. Range 6 to 16. Default 8. |
| active | boolean | when: action=set_active | set_active: true = switch on, false = switch off. |
| only_active | boolean | no | list: active only. Default false. |
| search | string | no | list: fragment of the name or code. Max 100 characters. |
| limit | integer | no | Maximum rows (default 50, max 200). |
| offset | integer | no | Rows to skip, for paging (default 0). |
| confirm | boolean | no | false (default) returns a preview and saves nothing. true executes, only after the user approved the preview, together with change_token. |
| change_token | string | when: confirm=true | Token from the preview. Required with confirm=true. Valid 30 minutes, single use, bound to the previewed arguments and data state. |
Limits
New codes start inactive unless activate=true. generate: up to 500 single-use codes per call. delete only for codes never used in an order. Rule without a code needs auto_apply. List max 200 rows (default 50). It is a write tool, so without an active licence it is hidden, list included; changes need the Commerce switch. Permission checked per action (AdminCartRules). Revertible with ps_revert_change.
What you see before anything is saved
Claude first calls the tool without confirming it. The module returns a preview (current and new values) and a single-use token valid for 30 minutes. Claude shows you the preview and saves the change only after your yes.
Related tools
- Category and brand promotions (catalogue price rules) ps_manage_catalog_price_rules
- Manage sale prices (specific prices) ps_manage_specific_prices
- Revert change ps_revert_change
Use cases with this tool
- Create a voucher code for a newsletter
- Give one customer a one-off apology code
- Review active voucher codes and discounts
- Prepare a Black Friday campaign across the shop
- Check free-shipping thresholds against your average order
- Deactivate expired and used-up voucher codes
- Offer free shipping from a set order amount
- Get the whole shop ready for Black Friday
- Clean up after a promotion
Last updated: 2026-10-11