> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create house discount

> Add a discount keyed to a buyer's corporate house

`POST /api/v2/storefront/house-discounts`

Creates a rate-card discount on the brand or operator axis. `(houseDomain, scope)`
is unique per storefront — a duplicate fails with `409`. To change an existing
row, [update](/v2/storefront/house-discounts/tasks/update-house-discount) it
instead.

## Request

```bash curl theme={null}
curl -X POST https://api.interchange.io/api/v2/storefront/house-discounts \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "houseDomain": "nike.com",
    "scope": "brand",
    "discountPercent": 12,
    "notes": "Negotiated 2026 Nike-house rate."
  }'
```

A `brand` discount on `nike.com` applies to every advertiser that rolls up to the
Nike house — a Converse buy (`converse.com → nike.com`) gets this rate. An
`operator` discount on `groupm.com` applies to every buy GroupM makes, whatever
the brand.

## Parameters

| Field             | Type                  | Required | Notes                                                                                                               |
| ----------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `houseDomain`     | string                | Yes      | Buyer-entity domain, e.g. `nike.com` (brand) or `groupm.com` (operator). Lowercased, no leading `www.`. 1–253 chars |
| `scope`           | `brand` \| `operator` | Yes      | Which buyer axis the discount applies to                                                                            |
| `discountPercent` | number                | Yes      | Discount off the quote, `0`–`100`. A `0` discount is stored but does not change any price                           |
| `notes`           | string \| null        | Yes      | Freeform notes, max 2000 chars. `null` for no notes                                                                 |

## Response

```json theme={null}
{
  "id": "17",
  "storefrontId": "1234",
  "houseDomain": "nike.com",
  "scope": "brand",
  "discountPercent": 12,
  "notes": "Negotiated 2026 Nike-house rate.",
  "createdAt": "2026-06-27T15:00:00.000Z",
  "updatedAt": "2026-06-27T15:00:00.000Z",
  "createdBy": "operator@touchline.example"
}
```

Returns `201` with the created row. The discount is floored at the storefront's
wholesale cost when applied, and the larger of this and any matching
[buyer instruction](/v2/storefront/buyer-instructions/overview) wins.

## Errors

* `400 VALIDATION_ERROR` — missing `houseDomain` or `scope`, or `discountPercent`
  outside `0`–`100`.
* `409 CONFLICT` — a discount already exists for this `(houseDomain, scope)`. The
  same domain may carry both a brand and an operator discount; only a same-axis
  duplicate conflicts. Update the existing row instead.
* `401 UNAUTHORIZED` — missing or invalid bearer token.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="House discount tasks" href="/v2/storefront/house-discounts/tasks" icon="list-check">
    All house-discount operations.
  </Card>

  <Card title="How a discount is chosen" href="/v2/storefront/house-discounts/overview" icon="sitemap">
    Nearest-ancestor within an axis, larger-of across axes.
  </Card>
</CardGroup>