Discounts

Create a discount

POST/v1/discounts

Requires sign-in (OAuth). Scope: discounts:write. MCP tool: create_discount.

Create a percentage, fixed-amount or free-shipping discount. Optionally set a minimum purchase and code prefix. The rule is saved to your discount library and Shopify immediately. Set minimum spend on the discount itself.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Human-friendly rule name shown in the discount library, e.g. "10% off over $50".

type*string

"percentage" = a percent off the order, "fixed" = a dollar amount off, "shipping" = free shipping. (Buy X Get Y discounts are created in the web app.)

value?number

percentage: the percent (e.g. 10 = 10% off, max 100). fixed: the dollar amount. shipping: omit.

duration_days?integer

How many days a minted code stays valid. Default 10.

minimum?|

Optional minimum-purchase requirement — THE place a "minimum spend" belongs (never audience filters). E.g. { "type": "subtotal", "value": 50 } = $50 minimum order.

code_prefix?string

Optional custom prefix for minted codes (e.g. "SAVE" → SAVE-XXXX). Omit for the default.

Response Body

`application/json`

curl -X POST "https://example.com/v1/discounts" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "type": "percentage"  }'

{  "id": "string",  "name": "string",  "offer": "string",  "minimum": {    "type": "string",    "value": 0  },  "duration_days": 0,  "note": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

Update a discount

PATCH/v1/discounts/{discount_rule_id}

Requires sign-in (OAuth). Scope: discounts:write. MCP tool: update_discount.

Edit a discount’s value, duration, name, code prefix or minimum purchase. Set minimum to null to remove the purchase requirement. Changes apply to codes created afterward.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

discount_rule_id*string

The id of an existing rule from your discount library — see get_campaign_composer_options.discount_rules.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Optional new library name. Omit to keep the current one.

type?string

Optional new discount kind (percentage / fixed / shipping). Omit to keep the current one.

value?number

Optional new value: the percent for percentage (max 100), the dollar amount for fixed.

duration_days?integer

Optional new validity window (days) for minted codes.

minimum?|

The minimum-purchase requirement. { "type": "subtotal", "value": 50 } sets a $50 minimum; { "type": "quantity", "value": 2 } a 2-item minimum; null REMOVES the minimum; omit to keep the current one. This is THE way to put a minimum on a discount — never audience filters.

code_prefix?string

Optional new prefix for minted codes. Pass "" to revert to the default prefix.

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/discounts/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "name": "string",  "offer": "string",  "minimum": {    "type": "string",    "value": 0  },  "duration_days": 0,  "note": "string"}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

{  "error": {    "code": "bad_request",    "message": "string"  }}

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`