---
title: "Create a placement"
method: POST
path: "/api/products/{productId}/placements"
tags: ["Products / Placements"]
---

# Create a placement

`POST /api/products/{productId}/placements`

## Request

- Base URL: `https://api.payware.eu`
- URL: `https://api.payware.eu/api/products/{productId}/placements`
- Auth: HTTP bearer

Up to 1,000 per product. The response carries the new pl id

## Path parameters

- `productId` string, required

## Request body

- PlacementRequest
  - `name` string, required: Placement name, up to 100 characters
  - `campaignId` string: The campaign it belongs to, if any
  - `medium` string, required: What the placement is: PRINT, PACKAGING, OUTDOOR, IN_STORE, EVENT, TV, RADIO, STREAMING, ONLINE, SOCIAL, EMAIL, SMS or OTHER
  - `carriers` string[], required: The methods that carry it: QR, BARCODE, NFC, BLE, LINK, SMS, SOUNDBITE (airs the product's audio)
  - `channel` string: Descriptive, e.g. the TV channel or the website, up to 100 characters
  - `location` string: Descriptive, e.g. the venue or the address, up to 255 characters
  - `externalRef` string: An agency's own code, up to 100 characters
  - `regions` string[]: ISO 3166-1 alpha-2 codes of the countries it airs in; empty means anywhere. Matched against the paying bank's country
  - `active` boolean: Whether it is in use. Governs airing and the soundbite attribution; a printed code keeps resolving until the placement is deleted
  - `activeFrom` string: Start of its active window, ISO-8601 with offset; empty means the product's
  - `activeTo` string: End of its active window, ISO-8601 with offset; empty means the product's

## Response `201`

Created

## Other responses

- `400`: Invalid placement, medium, carriers or regions, or the limit is reached
- `401`: Unauthenticated - missing, malformed or expired credentials
- `403`: Forbidden - the caller is authenticated but not permitted (plan or capability gate, KYC state, or tenant scope)
- `404`: ERR_MISSING_PRODUCT or ERR_MISSING_CAMPAIGN
- `429`: Too many requests - the caller exceeded its per-partner rate limit. Carries errorCode ERR_RATE_LIMIT_EXCEEDED and a Retry-After header, in seconds. The request was not processed, so the identical request is safe to retry once the window has passed.

---

[API](https://skmtc.dev/payware/apis/payware-api.md) · [All operations](https://skmtc.dev/payware/apis/payware-api/llms.txt) · [OpenAPI document](https://skmtc.dev/payware/apis/payware-api/revisions/7b3352ca947b?raw)