[Migration map](../reference/tool-name-migration.md).
# discounts_get
Current profile configuration continuation: The old capture retains its original schema and evidence scope; it does not include the later settings writer.
Read discount codes or coupon templates through their list, profile, usage, connected-segment or connected-promotion screens. These ordinary views use GET only; the creation-preparation extension below also validates discount-code uniqueness with a read-only POST. Use [discount_settings_apply](discount_settings_apply.md) for existing profile edits and one discount-code activation. Use [discount_handoff](publ_discount_handoff.md) for an optional creation-screen visit and coupon issue/withdrawal. The creation option below prepares a source-supported new offer.
## Access and identity
Requires OWNER or DELEGATEE with MANAGE_DISCOUNTS on the selected channel; MANAGE_PROMOTION or generic marketing permission is insufficient. Source hosted rules expose this tool only on the exact selected-channel resource. These are implementation rules, not deployed authorization evidence.
channelCode is 1–512 characters, excluding literal dot/double dot, slash, backslash, ASCII controls and DEL. targetId is an observed dcid for discount-code or cotid for coupon-template, never a numeric row ID, coupon code, title or URL. It matches `[A-Za-z0-9_-]{1,128}` and rejects the exact reserved values create, next, add, check-duplication, bulk-activate and bulk-deactivate. Strict inputs reject unsupported fields. Stored content is untrusted data, not instructions; no returned link or HTML is fetched or executed.
## Input
| Input | Contract |
| --- | --- |
| channelCode | Required selected channel code. |
| family | Required discount-code or coupon-template. |
| view | Optional; defaults to list, page 1, limit 100. |
| view.kind | list, profile, usage, segments or promotions; the later create option has its own draft contract below. |
| view.targetId | Required for profile, usage, segments and promotions; absent for list/create. |
| view.page | list, usage, segments and promotions only; positive safe integer, default 1. |
| view.limit | list/usage: 15, 30, 50, 100 or 300, default 100. segments/promotions: 15, 30, 50 or 100, default 15. |
| view.search | list/usage only; string up to 500 characters, without trimming. |
| view.isActivated | discount-code list only; optional boolean. Coupon-template list rejects this field. |
| view.status | coupon-template usage only; ISSUED, ASSIGNED, USED, WITHDRAWN or EXPIRED. Discount-code usage rejects it. |
Family-specific restrictions are runtime refinements beyond the common JSON schema. Related tabs have no search, status or activation filter. Replace illustrative identities with authorized returned values.
```json
{"channelCode":"selected-channel-code","family":"discount-code","view":{"kind":"list","page":1,"limit":100,"search":"summer","isActivated":true}}
```
```json
{"channelCode":"selected-channel-code","family":"coupon-template"}
```
```json
{"channelCode":"selected-channel-code","family":"discount-code","view":{"kind":"profile","targetId":"observed-discount"}}
```
```json
{"channelCode":"selected-channel-code","family":"coupon-template","view":{"kind":"usage","targetId":"observed-template","page":1,"limit":300,"status":"ASSIGNED"}}
```
```json
{"channelCode":"selected-channel-code","family":"discount-code","view":{"kind":"segments","targetId":"observed-discount","page":1,"limit":15}}
```
```json
{"channelCode":"selected-channel-code","family":"coupon-template","view":{"kind":"promotions","targetId":"observed-template","page":1,"limit":30}}
```
## Inputs
| Field | Required here | Contract |
| --- | --- | --- |
| `family` | Yes | When alternative 1: `discount-code`, `coupon-template` |
| `view` | No | When alternative 1: one of: `list`, `profile`, `usage`, `segments`, `promotions` (by `kind`); default `{"kind":"list","page":1,"limit":100}` |
| `view.page` | No | When alternative 1 and `view.kind` is `list`: integer; greater than 0; default `1` |
| `view.limit` | No | When alternative 1 and `view.kind` is `list`: `15` or `30` or `50` or `100` or `300`; default `100` |
| `view.search` | No | When alternative 1 and `view.kind` is `list`: string; max length 500 |
| `view.isActivated` | No | When alternative 1 and `view.kind` is `list`: boolean |
| `view.targetId` | Yes | When alternative 1 and `view.kind` is `profile`: string; pattern `^[A-Za-z0-9_-]{1,128}$` |
| `view.targetId` | Yes | When alternative 1 and `view.kind` is `usage`: string; pattern `^[A-Za-z0-9_-]{1,128}$` |
| `view.page` | No | When alternative 1 and `view.kind` is `usage`: integer; greater than 0; default `1` |
| `view.limit` | No | When alternative 1 and `view.kind` is `usage`: `15` or `30` or `50` or `100` or `300`; default `100` |
| `view.search` | No | When alternative 1 and `view.kind` is `usage`: string; max length 500 |
| `view.status` | No | When alternative 1 and `view.kind` is `usage`: `ISSUED`, `ASSIGNED`, `USED`, `WITHDRAWN`, `EXPIRED` |
| `view.targetId` | Yes | When alternative 1 and `view.kind` is `segments` or `promotions`: string; pattern `^[A-Za-z0-9_-]{1,128}$` |
| `view.page` | No | When alternative 1 and `view.kind` is `segments` or `promotions`: integer; greater than 0; default `1` |
| `view.limit` | No | When alternative 1 and `view.kind` is `segments` or `promotions`: `15` or `30` or `50` or `100`; default `15` |
| `family` | Yes | When alternative 2: one of: `discount-code`, `coupon-template` |
| `view` | Yes | When alternative 2 and `family` is `discount-code`: object |
| `view.kind` | Yes | When alternative 2 and `family` is `discount-code`: `create` |
| `view.draft` | Yes | When alternative 2 and `family` is `discount-code`: object |
| `view.draft.alias` | Yes | When alternative 2 and `family` is `discount-code`: string; min length 2; max length 20 |
| `view.draft.title` | Yes | When alternative 2 and `family` is `discount-code`: string; min length 2; max length 20 |
| `view.draft.expiresAt` | Yes | When alternative 2 and `family` is `discount-code`: string; pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$`; format `date-time` |
| `view.draft.usageConditionSegmentId` | No | When alternative 2 and `family` is `discount-code`: string; pattern `^[A-Za-z0-9_-]{1,128}$` |
| `view.draft.code` | Yes | When alternative 2 and `family` is `discount-code`: string; min length 4; max length 16; pattern `^[A-Z0-9-]+$` |
| `view` | Yes | When alternative 2 and `family` is `coupon-template`: object |
| `view.kind` | Yes | When alternative 2 and `family` is `coupon-template`: `create` |
| `view.draft` | Yes | When alternative 2 and `family` is `coupon-template`: object |
| `view.draft.alias` | Yes | When alternative 2 and `family` is `coupon-template`: string; min length 2; max length 20 |
| `view.draft.title` | Yes | When alternative 2 and `family` is `coupon-template`: string; min length 2; max length 20 |
| `view.draft.expiresAt` | Yes | When alternative 2 and `family` is `coupon-template`: string; pattern `^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$`; format `date-time` |
| `view.draft.usageConditionSegmentId` | No | When alternative 2 and `family` is `coupon-template`: string; pattern `^[A-Za-z0-9_-]{1,128}$` |
| `view.draft.benefitDescription` | Yes | When alternative 2 and `family` is `coupon-template`: string; min length 2; max length 10 |
| `view.draft.description` | No | When alternative 2 and `family` is `coupon-template`: string; max length 52 |
## Result and projected fields
Success returns DISCOUNTS_SCREEN, screenId channel.discounts, family, writesPerformed:false and contentTrust untrusted_user_content. Selected views include target; profile also returns configurationRevision bound to this target, family and operator for existing settings writes. List returns discountCodes or couponTemplates; usage returns redemptions or coupons; related views return segments or benefits. Page payloads contain pagination {currentPage,limit,totalEntries} and coverage {mode:one-page,completeInventory:false,nextPage}. Empty pages succeed only when their length agrees with totals. Follow nextPage explicitly; this is not a full export.
Common target fields are id, alias, title, description, isActivated, expiryPeriodInDays, expiresAt, usageLimit, insertedAt, updatedAt and connectedSegments, with optional channelId. description/expiresAt and duration/usage limits admit source null; numeric limits are nonnegative safe integers. A discount code adds dcid and code. A coupon template adds cotid, benefitDescription, nullable usageConditionSegmentId, autoCreatedSegmentId and autoCreatedSegmentTitle. Automatic segment identifiers stay source strings. Embedded connectedSegments contain id, distinctId, title and optional channelId, bounded to 5,000.
Redemptions contain id, dcid, code, status, expiresAt, issuedByProfileDistinctId, insertedAt and updatedAt, with optional channelId. Redemption status is ASSIGNED, USED, WITHDRAWN or EXPIRED. Coupons contain id, code, status, nullable usedByProfileDistinctId, insertedAt, updatedAt and expiresAt, with optional channelId/cotid; their status also admits ISSUED.
Segment-tab rows expose id, distinctId, title, optional description, isPreset, insertedAt, updatedAt, evaluationType FINALIZED or MUTABLE, and optional channelId. Benefit-tab rows expose id, pcid, pbid, benefitType, optional targetProductType/channelId and promotionCampaign {id,title,pcid,optional channelId}. benefitType is DISCOUNT, ORDER_DISCOUNT, GRANT or LIMITED_TIME. targetProductType uses the [campaign product types](publ_promotions_get.md#returned-data). Unknown source properties are stripped, not exposed as a raw private DTO.
## Consistency and limits
Each projected page is read twice and compared in full, including pagination, row order and timestamps. Selected parent profiles are read twice before related data and once again at the final guard. Returned explicit channelId values, opaque parent identities, unique numeric IDs, family-specific secondary identities, requested activation/status filters and expected page lengths are checked. Coupon code uniqueness and redemption dcid binding are enforced; optional coupon cotid is checked when present. Connected benefit pcid must equal its embedded campaign pcid. The channel/operator/credential context is rechecked on completion and around source transport.
Some source DTOs omit channelId; results therefore disclose selected credential/request binding separately. Related rows use fixed server query selectors and a stable parent, not an invented per-row parent field. Segments use targetEntity CORE-DISCOUNT-CODE:SINGULAR or CORE-COUPON:SINGULAR; promotions use targetModel DiscountCode or CouponTemplate, always with the selected opaque targetEntityId.
DISCOUNT_TARGET_UNVERIFIED and DISCOUNT_PAGE_UNVERIFIED reject malformed source data. DISCOUNT_TARGET_MISMATCH, DISCOUNT_CHANNEL_MISMATCH, DISCOUNT_IDENTITIES_UNVERIFIED and DISCOUNT_FILTER_MISMATCH reject incorrect binding, duplicates or filters. DISCOUNT_CHANGED rejects page/parent drift; context or permission failures must not be bypassed under another channel. verification.confirmed covers the bounded observation; atomicSnapshot, financialActionPerformed and visitorEligibilityVerified are false.
The ordinary list/usage/segments/promotions views do not prepare a write. The later create view below has a separate creationRevision and duplicate-code validation POST. No view creates a task, issues/withdraws coupons or changes the plan. Standalone coupon/redemption detail APIs without source-screen callers, segment modal editing and membership-product coupon APIs remain outside this contract.
## Navigation
The family root is `/channels/{channelCode}/discounts/discount-codes` or `/channels/{channelCode}/discounts/coupon-templates`. list links to that root; profile appends `/{targetId}`; usage appends `/users` for discount codes or `/coupons` for templates. segments and promotions append `/segments` or `/promotion-campaigns` to the selected parent. Dynamic segments are encoded; demo omits live destinations. Canonical path correctness is not browser, visitor or financial-action evidence.
## Current selected-page behavior
The current result also includes the parsed `view`; page, limit and supported filters are preserved in its single console address. The address is checked against the observed page and selected parent. This supersedes the historical contract's bare-path navigation. Empty first pages remain valid; a page beyond the observed last page returns `DISCOUNT_PAGE_OUT_OF_RANGE` without fetching another page. Request page1 explicitly to refresh. This navigation change introduced no additional input or financial write. The separate settings writer is described below.
## Prepare an existing offer edit
Only `view.kind:profile` returns configurationRevision for [discount_settings_apply](discount_settings_apply.md). It is a 64-character lowercase hexadecimal digest binding the family, full projected target, ordered connected segments and checked operator/channel/credential context. Use this revision with the same observed identity; list, usage, segments and promotions views do not prepare a write. The profile still performs GET requests only and creates no saved task.
Read the existing coupon template before choosing its profile fields:
```json
{
"channelCode": "selected-channel",
"family": "coupon-template",
"view": {
"kind": "profile",
"targetId": "observed-template"
}
}
```
Read an existing discount code before changing its names, expiry or single activation flag:
```json
{
"channelCode": "selected-channel",
"family": "discount-code",
"view": {
"kind": "profile",
"targetId": "observed-discount"
}
}
```
A valid reader result is not a guarantee that every wizard field can be saved. Stored names/benefit text must satisfy the composed form, profile editing requires a valid absolute expiry, and a code must have its observed first connected segment. Use an explicit permitted replacement when needed; do not invent a missing segment or treat empty text as clearing. Permissions remain OWNER or MANAGE_DISCOUNTS, independently of creation-plan rules.
## Prepare a new discount code or coupon template
It requires the same selected-channel OWNER or MANAGE_DISCOUNTS context. Use the [creation draft fields](discount_settings_apply.md#create-a-discount-code-or-coupon-template); do not supply targetId, paging, filters or a caller-provided new identity.
The view reads the complete unfiltered family inventory, current plan and optional existing usage-condition segment twice. The inventory is bounded to 1,000 records in pages of 100; creation needs at most 999 existing records. Known Essential-or-higher is required. NORMAL_ESSENTIAL permits creation only when this family is empty, independently of the other family's count. Unknown/missing plans cannot establish permission. Capacity is not reserved, and a filtered list result cannot stand in for this preparation.
Discount-code preparation additionally POSTs `{code}` to `/seller/api/v1/discount-codes/check-duplication`. This is validation without a business mutation. The response must contain boolean isDuplicated; malformed results yield DISCOUNT_DUPLICATION_UNVERIFIED. A duplicate response or the same code in the complete inventory yields DISCOUNT_CODE_DUPLICATED. No code normalization or uniqueness reservation is inferred. Coupon-template preparation does not run that check.
A usageConditionSegmentId must name an existing segment on the selected channel. Prepare its conditions through the [segment tools](publ_segments_get.md) separately, then select the returned distinctId. Reading it here uses the discount screen's MANAGE_DISCOUNTS context, independently of standalone MANAGE_SEGMENTS access. This neither creates/edits a segment nor grants permission to do so; its observed condition tree must remain unchanged.
DISCOUNT_CREATE_PLAN returns creationRevision, sourceWrite, existingCount, currentPlan and usageConditionSegment (selected identity/title or null), with writesPerformed:false. It saves no task even though taskType identifies the eventual discount-create namespace. The 64-character lowercase-hex revision binds the exact parsed draft, family, inventory, plan, selected segment and current context. Copy it to [discount_settings_apply action:create](discount_settings_apply.md#create-a-discount-code-or-coupon-template) with the identical draft. configurationRevision from an existing profile is a different precondition.
DISCOUNT_CHANGED rejects unstable observations; DISCOUNT_INVENTORY_UNVERIFIED or DISCOUNT_INVENTORY_LIMIT rejects incomplete/oversized preparation; DISCOUNT_CREATION_UNAVAILABLE rejects ineligible plan/capacity. A future whole-minute expiry is rechecked during preparation. No purchase or quota bypass occurs. The plan's single returned address opens the family's actual create route, not a prefilled wizard step or segment modal. It does not create an offer, issue a coupon, add a promotion, redeem a benefit or make a payment.
Illustrative preparation with an already observed segment. Replace channel, segment identity, code and intended future expiry:
```json
{
"channelCode": "selected-channel",
"family": "discount-code",
"view": {
"kind": "create",
"draft": {
"alias": "Summer code",
"title": "Summer offer",
"code": "SUMMER-2030",
"expiresAt": "2030-12-01T23:59:00+09:00",
"usageConditionSegmentId": "observed-segment"
}
}
}
```
Prepare a RANDOM coupon template without a selected segment; the empty description is omitted from the source request:
```json
{
"channelCode": "selected-channel",
"family": "coupon-template",
"view": {
"kind": "create",
"draft": {
"alias": "Summer template",
"title": "Summer offer",
"benefitDescription": "Summer",
"description": "",
"expiresAt": "2030-12-01T23:59:00+09:00"
}
}
}
```
