> For the complete documentation index, see [llms.txt](https://help.recart.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.recart.com/developers/public-api/discount/create-a-discount-draft.md).

# Create a discount draft

**Not yet enabled for merchant accounts.** Returns `403` `ERR_WRITE_NOT_ALLOWED` until enabled for your account.

Creates a draft, not a discount: nothing is created on Shopify. The draft holds the effective settings — the request's settings with every default filled in — so they can be reviewed before the discount is published with `POST /discounts/{id}/publish`. The draft can be read with `GET /discounts/{id}` until it expires.

The code of a general discount is checked with Shopify, so a code already in use, in Recart or on Shopify, fails here and no draft is stored.

```json
{"openapi":"3.1.0","info":{"title":"Recart API","version":"2023-12"},"tags":[{"name":"Discount","description":"Discounts"}],"servers":[{"url":"https://api.recart.com/app-integrations/2023-12","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Recart-API-Key","description":"It can be obtained in Recart account after contacting Support"}},"schemas":{"PostDiscount":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["discounts"]},"attributes":{"$ref":"#/components/schemas/DiscountSettings"}}},"DiscountSettings":{"type":"object","description":"The settings of a new discount. Every discount applies to all\nproducts, all customers, all countries and one-time purchases only.\nPercentage and fixed amount discounts are order discounts, free\nshipping is a shipping discount; combinesWith is judged against that\nclass. Amounts are in the store currency, which the draft echoes in\neffectiveSettings.currency.\n\nOnce published, the discount keeps the draft's id, and its settings\nread in `GET /discounts` as below. An attribute without a value\nholds the setting's value unchanged.\n\n| Setting | `GET /discounts` attributes |\n| --- | --- |\n| `name` | `name` |\n| `startsAt` | `startsAt` (absent on expiring discounts) |\n| `shape.type: general` | `customizationType: general` |\n| `shape.type: refilling_pool` | `customizationType: unique`, `expiryType: fixed`, `mode: refilling` |\n| `shape.type: non_refilling_pool` | `customizationType: unique`, `expiryType: fixed`, `mode: non-refilling` |\n| `shape.type: expiring` | `customizationType: unique`, `expiryType: relative` |\n| `shape.code` | `code` |\n| `shape.codePrefix` | `discountCodePattern: <codePrefix>{RAND}` (`WELCOME` reads as `WELCOME{RAND}`) |\n| `shape.targetCount` | `targetCount` |\n| `shape.validForHours` | `durationSeconds: validForHours × 3600` |\n| `shape.endsAt` | `endsAt` |\n| `value.type: percentage` | `valueType: PERCENTAGE`, `type: basic`, `discountClasses: [order]` |\n| `value.percent` | `amount: percent / 100` (15 reads as 0.15) |\n| `value.type: fixed_amount` | `valueType: FIXED_AMOUNT`, `type: basic`, `discountClasses: [order]` |\n| `value.amount` | `amount` |\n| `value.type: free_shipping` | `valueType: FREE_SHIPPING`, `type: free-shipping`, `discountClasses: [shipping]`, `amount: 1` |\n| `value.maximumShippingPrice`, `minimumRequirement`, `combinesWith`, `limits` | in `summary`, and in `template` on expiring discounts |\n","additionalProperties":false,"required":["name","shape","value"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Name of the discount, also its title on Shopify"},"shape":{"$ref":"#/components/schemas/DiscountShape"},"value":{"$ref":"#/components/schemas/DiscountValue"},"startsAt":{"type":"string","format":"date-time","description":"Default: now"},"minimumRequirement":{"$ref":"#/components/schemas/DiscountMinimumRequirement"},"combinesWith":{"type":"object","description":"Which other discounts it can be combined with in one checkout,\nsee https://help.shopify.com/en/manual/discounts/discount-combinations.\nEach omitted key defaults to false.\n","additionalProperties":false,"properties":{"orderDiscounts":{"type":"boolean"},"productDiscounts":{"type":"boolean"},"shippingDiscounts":{"type":"boolean"}}},"limits":{"type":"object","additionalProperties":false,"properties":{"totalUses":{"type":"integer","minimum":1,"description":"Total redemptions; on a code pool it counts across every code\nand stops the whole pool. Default: unlimited\n"},"oncePerCustomer":{"type":"boolean","description":"Default: false"}}}}},"DiscountShape":{"description":"general = one shared code. A code pool or an expiring discount gives\neach customer a different code, starting with the code prefix. Refilling\npools serve flows and popups, non-refilling pools serve campaigns,\nexpiring codes are for urgency.\n","oneOf":[{"$ref":"#/components/schemas/DiscountShapeGeneral"},{"$ref":"#/components/schemas/DiscountShapeRefillingPool"},{"$ref":"#/components/schemas/DiscountShapeNonRefillingPool"},{"$ref":"#/components/schemas/DiscountShapeExpiring"}],"discriminator":{"propertyName":"type","mapping":{"general":"#/components/schemas/DiscountShapeGeneral","refilling_pool":"#/components/schemas/DiscountShapeRefillingPool","non_refilling_pool":"#/components/schemas/DiscountShapeNonRefillingPool","expiring":"#/components/schemas/DiscountShapeExpiring"}}},"DiscountShapeGeneral":{"type":"object","additionalProperties":false,"required":["type","code","endsAt"],"properties":{"type":{"type":"string","enum":["general"]},"code":{"type":"string","minLength":1,"maxLength":200,"description":"The shared code customers enter at checkout"},"endsAt":{"$ref":"#/components/schemas/DiscountEndsAt"}}},"DiscountEndsAt":{"type":["string","null"],"format":"date-time","description":"Required; null = the discount never expires"},"DiscountShapeRefillingPool":{"type":"object","description":"Recart sets the number of codes in a refilling pool; the request\ncannot. effectiveSettings.shape.targetCount shows it.\n","additionalProperties":false,"required":["type","codePrefix","endsAt"],"properties":{"type":{"type":"string","enum":["refilling_pool"]},"codePrefix":{"$ref":"#/components/schemas/DiscountCodePrefix"},"endsAt":{"$ref":"#/components/schemas/DiscountEndsAt"}}},"DiscountCodePrefix":{"type":"string","minLength":1,"maxLength":200},"DiscountShapeNonRefillingPool":{"type":"object","additionalProperties":false,"required":["type","codePrefix","targetCount","endsAt"],"properties":{"type":{"type":"string","enum":["non_refilling_pool"]},"codePrefix":{"$ref":"#/components/schemas/DiscountCodePrefix"},"targetCount":{"type":"integer","minimum":1,"description":"Number of codes in the pool"},"endsAt":{"$ref":"#/components/schemas/DiscountEndsAt"}}},"DiscountShapeExpiring":{"type":"object","additionalProperties":false,"required":["type","codePrefix","validForHours"],"properties":{"type":{"type":"string","enum":["expiring"]},"codePrefix":{"$ref":"#/components/schemas/DiscountCodePrefix"},"validForHours":{"type":"integer","minimum":1,"description":"How long each code is valid from the moment it is issued to the customer"}}},"DiscountValue":{"oneOf":[{"$ref":"#/components/schemas/DiscountValuePercentage"},{"$ref":"#/components/schemas/DiscountValueFixedAmount"},{"$ref":"#/components/schemas/DiscountValueFreeShipping"}],"discriminator":{"propertyName":"type","mapping":{"percentage":"#/components/schemas/DiscountValuePercentage","fixed_amount":"#/components/schemas/DiscountValueFixedAmount","free_shipping":"#/components/schemas/DiscountValueFreeShipping"}}},"DiscountValuePercentage":{"type":"object","additionalProperties":false,"required":["type","percent"],"properties":{"type":{"type":"string","enum":["percentage"]},"percent":{"type":"number","minimum":1,"maximum":100,"description":"Off the entire order"}}},"DiscountValueFixedAmount":{"type":"object","additionalProperties":false,"required":["type","amount"],"properties":{"type":{"type":"string","enum":["fixed_amount"]},"amount":{"type":"number","exclusiveMinimum":0,"description":"Off the entire order, in the store currency"}}},"DiscountValueFreeShipping":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["free_shipping"]},"maximumShippingPrice":{"type":"number","exclusiveMinimum":0,"description":"Free shipping only on rates up to this price, in the store currency. Default: no maximum"}}},"DiscountMinimumRequirement":{"description":"Default: none","oneOf":[{"$ref":"#/components/schemas/DiscountMinimumSubtotal"},{"$ref":"#/components/schemas/DiscountMinimumQuantity"}],"discriminator":{"propertyName":"type","mapping":{"subtotal":"#/components/schemas/DiscountMinimumSubtotal","quantity":"#/components/schemas/DiscountMinimumQuantity"}}},"DiscountMinimumSubtotal":{"type":"object","additionalProperties":false,"required":["type","amount"],"properties":{"type":{"type":"string","enum":["subtotal"]},"amount":{"type":"number","exclusiveMinimum":0,"description":"Minimum order subtotal, in the store currency"}}},"DiscountMinimumQuantity":{"type":"object","additionalProperties":false,"required":["type","quantity"],"properties":{"type":{"type":"string","enum":["quantity"]},"quantity":{"type":"integer","minimum":1,"description":"Minimum number of items in the order"}}},"DiscountDraft":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["discounts"]},"attributes":{"type":"object","required":["id","status","effectiveSettings","defaultsApplied","warnings","expiresAt"],"properties":{"id":{"type":"string","description":"ID of the draft; the published discount keeps it"},"status":{"type":"string","enum":["draft"]},"effectiveSettings":{"$ref":"#/components/schemas/EffectiveDiscountSettings"},"defaultsApplied":{"type":"array","description":"The settings the API filled in: a whole setting when it was\nomitted (e.g. limits), or one key of it when the setting was\ngiven without that key (e.g. limits.totalUses)\n","items":{"type":"string"}},"warnings":{"type":"array","description":"Values that are allowed but risky, to show to the user before publishing","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time","description":"The draft is deleted after this time"}}}}},"EffectiveDiscountSettings":{"type":"object","description":"The settings the discount will be created with: the request's\nsettings with every default filled in.\n","required":["name","shape","value","startsAt","combinesWith","limits","currency"],"properties":{"name":{"type":"string"},"shape":{"oneOf":[{"$ref":"#/components/schemas/DiscountShapeGeneral"},{"$ref":"#/components/schemas/EffectiveDiscountShapeRefillingPool"},{"$ref":"#/components/schemas/DiscountShapeNonRefillingPool"},{"$ref":"#/components/schemas/DiscountShapeExpiring"}],"discriminator":{"propertyName":"type","mapping":{"general":"#/components/schemas/DiscountShapeGeneral","refilling_pool":"#/components/schemas/EffectiveDiscountShapeRefillingPool","non_refilling_pool":"#/components/schemas/DiscountShapeNonRefillingPool","expiring":"#/components/schemas/DiscountShapeExpiring"}}},"value":{"$ref":"#/components/schemas/DiscountValue"},"startsAt":{"type":"string","format":"date-time"},"minimumRequirement":{"$ref":"#/components/schemas/DiscountMinimumRequirement"},"combinesWith":{"type":"object","required":["orderDiscounts","productDiscounts","shippingDiscounts"],"properties":{"orderDiscounts":{"type":"boolean"},"productDiscounts":{"type":"boolean"},"shippingDiscounts":{"type":"boolean"}}},"limits":{"type":"object","required":["oncePerCustomer"],"properties":{"totalUses":{"type":"integer","description":"Absent = unlimited"},"oncePerCustomer":{"type":"boolean"}}},"currency":{"type":"string","description":"The store currency of every amount"}}},"EffectiveDiscountShapeRefillingPool":{"type":"object","required":["type","codePrefix","targetCount","endsAt"],"properties":{"type":{"type":"string","enum":["refilling_pool"]},"codePrefix":{"type":"string"},"targetCount":{"type":"integer","description":"Number of codes in the pool"},"endsAt":{"$ref":"#/components/schemas/DiscountEndsAt"}}},"HttpErrorBody":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["id","code","title","detail"],"properties":{"id":{"type":"string"},"code":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}}},"responses":{"HttpError":{"description":"HTTP Error response","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}}}},"paths":{"/discounts":{"post":{"summary":"Create a discount draft","tags":["Discount"],"operationId":"createDiscountDraft","description":"**Not yet enabled for merchant accounts.** Returns `403`\n`ERR_WRITE_NOT_ALLOWED` until enabled for your account.\n\nCreates a draft, not a discount: nothing is created on Shopify. The\ndraft holds the effective settings — the request's settings with\nevery default filled in — so they can be reviewed before the\ndiscount is published with `POST /discounts/{id}/publish`. The\ndraft can be read with `GET /discounts/{id}` until it expires.\n\nThe code of a general discount is checked with Shopify, so a code\nalready in use, in Recart or on Shopify, fails here and no draft is\nstored.\n","requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PostDiscount"}}}}}},"responses":{"201":{"description":"The draft was created","content":{"application/vnd.api+json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/DiscountDraft"}}}}}},"400":{"description":"`ERR_BAD_REQUEST` — the payload failed validation, in which case\n`detail` lists the offending fields. Also returned for a rule\nthat spans several settings, such as `endsAt` before `startsAt`.\n\n`ERR_CODE_TAKEN` — another discount already uses the code.\n`detail` is `discount-exists` when it is a Recart discount, and\n`price-rule-exists-in-shopify` when it exists only on Shopify.\nNo draft is stored.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"401":{"description":"`ERR_UNAUTHORIZED` — the API key is missing.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"403":{"description":"`ERR_FORBIDDEN` — the API key is unknown or has been revoked.\n\n`ERR_WRITE_NOT_ALLOWED` — creating discounts is not enabled for\nthis account. Do not retry.\n\n`ERR_SHOPIFY_ACCESS_DENIED` — Shopify denied access to the\nstore's discounts. Creating cannot work until the store's Shopify\nconnection is fixed. Do not retry.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"429":{"description":"`ERR_LIMIT_REACHED` — the draft limit of the site is\nreached. `detail` names the limit and when it resets.\n","headers":{"Retry-After":{"description":"Seconds until the limit resets","schema":{"type":"integer"}}},"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"4XX":{"$ref":"#/components/responses/HttpError"},"5XX":{"$ref":"#/components/responses/HttpError"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.recart.com/developers/public-api/discount/create-a-discount-draft.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
