Skip to content

chore(docs): sync generated API reference and schema tables #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dylandepass wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(docs): sync generated API reference and schema tables #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 136 additions & 0 deletions api/batch-create-coupons.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Batch-generate coupon codes — Helix Commerce API</title>
<meta name="description" content="Generates `count` (max 500) unique codes with an optional `prefix`, all referencing the given coupon type.">
<meta name="template" content="docs"/>
<meta name="labs" content="Commerce"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="stylesheet" href="/styles/styles.css"/>
<script type="importmap">
{
"imports": {
"prismjs": "/deps/prismjs/prism.js",
"da-lit": "https://da.live/deps/lit/dist/index.js",
"da-y-wrapper": "https://da.live/deps/da-y-wrapper/dist/index.js"
}
}
</script>
<script src="/scripts/nx.js" type="module"></script>
<script src="/scripts/scripts.js" type="module"></script>
<link rel="icon" href="data:,">
</head>
<body>
<header></header>
<main>
<div>
<p class="api-eyebrow">Coupons</p>
<h1>Batch-generate coupon codes</h1>
<p class="endpoint"><span class="http-method http-post">POST</span> <code class="http-path">/{org}/sites/{site}/coupons/batch</code></p>
<p class="api-base-url"><span class="api-base-url-label">Base URL</span> <code>https://api.adobecommerce.live</code> · Staging <code>https://api-stage.adobecommerce.live</code></p>
<p>Generates `count` (max 500) unique codes with an optional `prefix`, all referencing the given coupon type.</p>
<p class="permissions">Required permissions: <code>coupons:write</code></p>
<h2>Path parameters</h2>
<div class="table">
<table>
<tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>org</code></td><td><code>string</code></td><td>yes</td><td>Organization identifier.</td></tr>
<tr><td><code>site</code></td><td><code>string</code></td><td>yes</td><td>Site identifier.</td></tr>
</table>
</div>
<h2>Request headers</h2>
<div class="table">
<table>
<tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>Authorization</code></td><td><code>string</code></td><td>yes</td><td>Bearer token. `Bearer &lt;jwt&gt;`.</td></tr>
<tr><td><code>Content-Type</code></td><td><code>string</code></td><td>yes</td><td>Must be `application/json`.</td></tr>
</table>
</div>
<h2>Request body</h2>
<div class="table">
<table>
<tr><td>Field</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>typeId</code></td><td><code>string</code></td><td>yes</td><td>Coupon type the generated codes reference.</td></tr>
<tr><td><code>count</code></td><td><code>integer</code></td><td>no</td><td>Number of codes to generate (max 500). Defaults to 1.</td></tr>
<tr><td><code>prefix</code></td><td><code>string</code></td><td>no</td><td>Optional code prefix. Defaults to "CODE".</td></tr>
<tr><td><code>discountOverride</code></td><td><code>object | null</code></td><td>no</td><td>Overrides the coupon type's flat discount for this code. Not allowed when the type is a product-list coupon.</td></tr>
<tr><td><code>usageLimit</code></td><td><code>number | null</code></td><td>no</td><td>Total redemption limit for every code; null for unlimited.</td></tr>
<tr><td><code>usesPerCustomer</code></td><td><code>number | null</code></td><td>no</td><td>Per-customer redemption limit for every code; null for unlimited.</td></tr>
<tr><td><code>expiresAt</code></td><td><code>string</code></td><td>no</td><td>Expiry timestamp (ISO 8601) applied to every generated code.</td></tr>
</table>
</div>
<h2>Response</h2>
<h3><span class="status-badge status-2xx">201</span> The generated code count and code names.</h3>
<div class="table">
<table>
<tr><td>Field</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>count</code></td><td><code>integer</code></td><td>yes</td><td>Number of codes generated.</td></tr>
<tr><td><code>codes</code></td><td><code>string[]</code></td><td>yes</td><td>The generated code names.</td></tr>
</table>
</div>
<h3><span class="status-badge status-4xx">400</span> Missing typeId, or referenced coupon type not found.</h3>
<div class="table">
<table>
<tr><td>Field</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>code</code></td><td><code>string</code></td><td>yes</td><td>Machine-readable error code.</td></tr>
<tr><td><code>message</code></td><td><code>string</code></td><td>yes</td><td>Human-readable error message.</td></tr>
<tr><td><code>errors</code></td><td><code>object[]</code></td><td>no</td><td>Per-field validation failures.</td></tr>
</table>
</div>
<h3><span class="status-badge status-4xx">405</span> Method not allowed — only POST.</h3>
<div class="table">
<table>
<tr><td>Field</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>code</code></td><td><code>string</code></td><td>yes</td><td>Machine-readable error code (also sent as the `x-error-code` header).</td></tr>
<tr><td><code>message</code></td><td><code>string</code></td><td>yes</td><td>Human-readable error message (also sent as the `x-error` header).</td></tr>
<tr><td><code>resource</code></td><td><code>string</code></td><td>no</td><td>The resource type involved, when applicable.</td></tr>
<tr><td><code>retryable</code></td><td><code>boolean</code></td><td>no</td><td>Whether the caller may retry the request.</td></tr>
<tr><td><code>details</code></td><td><code>object</code></td><td>no</td><td>Optional structured detail.</td></tr>
</table>
</div>
</div>
<div class="code-rail">
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">POST /{org}/sites/{site}/coupons/batch</span></div>
<pre><code class="language-json">{
"typeId": "summer-10",
"count": 50,
"prefix": "SUMMER"
}</code></pre>
</div>
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">Response · <span class="code-status status-2xx">201</span></span></div>
<pre><code class="language-json">{
"count": 2,
"codes": [
"SUMMER-ABCD1234",
"SUMMER-EFGH5678"
]
}</code></pre>
</div>
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">Response · <span class="code-status status-4xx">400</span></span></div>
<pre><code class="language-json">{
"code": "validation_failed",
"message": "invalid request",
"errors": [
{
"path": "$.typeId",
"message": "is required"
}
]
}</code></pre>
</div>
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">Response · <span class="code-status status-4xx">405</span></span></div>
<pre><code class="language-json">{
"code": "method_not_allowed",
"message": "GET not allowed"
}</code></pre>
</div>
</div>
</main>
<footer></footer>
</body>
</html>
130 changes: 130 additions & 0 deletions api/create-coupon-type.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Create a coupon type — Helix Commerce API</title>
<meta name="description" content="Validates and stores a coupon type. `id` and `name` are required, plus exactly one discount shape: a flat `discountType`/`discountValue`, or a "product list coupon" `discountedProducts` array. The two shapes are mutually exclusive, as are `country`/`countries`; included/excluded products and categories may not overlap.">
<meta name="template" content="docs"/>
<meta name="labs" content="Commerce"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="stylesheet" href="/styles/styles.css"/>
<script type="importmap">
{
"imports": {
"prismjs": "/deps/prismjs/prism.js",
"da-lit": "https://da.live/deps/lit/dist/index.js",
"da-y-wrapper": "https://da.live/deps/da-y-wrapper/dist/index.js"
}
}
</script>
<script src="/scripts/nx.js" type="module"></script>
<script src="/scripts/scripts.js" type="module"></script>
<link rel="icon" href="data:,">
</head>
<body>
<header></header>
<main>
<div>
<p class="api-eyebrow">Coupons</p>
<h1>Create a coupon type</h1>
<p class="endpoint"><span class="http-method http-post">POST</span> <code class="http-path">/{org}/sites/{site}/coupons/types</code></p>
<p class="api-base-url"><span class="api-base-url-label">Base URL</span> <code>https://api.adobecommerce.live</code> · Staging <code>https://api-stage.adobecommerce.live</code></p>
<p>Validates and stores a coupon type. `id` and `name` are required, plus exactly one discount shape: a flat `discountType`/`discountValue`, or a "product list coupon" `discountedProducts` array. The two shapes are mutually exclusive, as are `country`/`countries`; included/excluded products and categories may not overlap.</p>
<p class="permissions">Required permissions: <code>coupons:write</code></p>
<h2>Path parameters</h2>
<div class="table">
<table>
<tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>org</code></td><td><code>string</code></td><td>yes</td><td>Organization identifier.</td></tr>
<tr><td><code>site</code></td><td><code>string</code></td><td>yes</td><td>Site identifier.</td></tr>
</table>
</div>
<h2>Request headers</h2>
<div class="table">
<table>
<tr><td>Name</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>Authorization</code></td><td><code>string</code></td><td>yes</td><td>Bearer token. `Bearer &lt;jwt&gt;`.</td></tr>
<tr><td><code>Content-Type</code></td><td><code>string</code></td><td>yes</td><td>Must be `application/json`.</td></tr>
</table>
</div>
<h2>Response</h2>
<h3><span class="status-badge status-2xx">201</span> The created coupon type.</h3>
<h3><span class="status-badge status-4xx">400</span> Validation failed (missing/invalid fields, mutually exclusive fields, category overlap, duplicate discountedProducts).</h3>
<div class="table">
<table>
<tr><td>Field</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>code</code></td><td><code>string</code></td><td>yes</td><td>Machine-readable error code.</td></tr>
<tr><td><code>message</code></td><td><code>string</code></td><td>yes</td><td>Human-readable error message.</td></tr>
<tr><td><code>errors</code></td><td><code>object[]</code></td><td>no</td><td>Per-field validation failures.</td></tr>
</table>
</div>
<h3><span class="status-badge status-4xx">409</span> A coupon type with this id already exists.</h3>
<div class="table">
<table>
<tr><td>Field</td><td>Type</td><td>Required</td><td>Description</td></tr>
<tr><td><code>code</code></td><td><code>string</code></td><td>yes</td><td>Machine-readable error code (also sent as the `x-error-code` header).</td></tr>
<tr><td><code>message</code></td><td><code>string</code></td><td>yes</td><td>Human-readable error message (also sent as the `x-error` header).</td></tr>
<tr><td><code>resource</code></td><td><code>string</code></td><td>no</td><td>The resource type involved, when applicable.</td></tr>
<tr><td><code>retryable</code></td><td><code>boolean</code></td><td>no</td><td>Whether the caller may retry the request.</td></tr>
<tr><td><code>details</code></td><td><code>object</code></td><td>no</td><td>Optional structured detail.</td></tr>
</table>
</div>
</div>
<div class="code-rail">
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">POST /{org}/sites/{site}/coupons/types</span></div>
<pre><code class="language-json">{
"id": "summer-10",
"name": "10% Off Summer",
"discountType": "percentage",
"discountValue": 10,
"minimumOrderAmount": 50,
"maximumDiscountAmount": 100,
"freeShipping": false,
"stackable": true
}</code></pre>
</div>
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">Response · <span class="code-status status-2xx">201</span></span></div>
<pre><code class="language-json">{
"id": "summer-10",
"name": "10% Off Summer",
"discountType": "percentage",
"discountValue": 10,
"minimumOrderAmount": 50,
"maximumDiscountAmount": 100,
"freeShipping": false,
"stackable": true,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}</code></pre>
</div>
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">Response · <span class="code-status status-4xx">400</span></span></div>
<pre><code class="language-json">{
"code": "validation_failed",
"message": "invalid request",
"errors": [
{
"path": "$.id",
"message": "is required"
}
]
}</code></pre>
</div>
<div class="code-sample">
<div class="code-sample-head"><span class="code-sample-title">Response · <span class="code-status status-4xx">409</span></span></div>
<pre><code class="language-json">{
"code": "already_exists",
"message": "coupon type summer-10 already exists",
"resource": "coupon_type",
"details": {
"typeId": "summer-10"
}
}</code></pre>
</div>
</div>
</main>
<footer></footer>
</body>
</html>
Loading