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

# Create Promotion URL

> Create a landing-page destination for all affiliates, selected groups, or selected products

Create a promotion URL. The `audience` determines which assignment field is required:

* `all_affiliates`: omit both `group_ids` and `product_ids`.
* `groups`: provide one or more `group_ids` and omit `product_ids`.
* `products`: provide one or more `product_ids` and omit `group_ids`.

All referenced groups must belong to the program and products must belong to your team. Duplicate assignment IDs are accepted and stored once.

## Body Parameters

<ParamField body="name" type="string" required>Display name, 1–255 characters.</ParamField>
<ParamField body="url" type="string" required>HTTP(S) destination URL, up to 2048 characters.</ParamField>
<ParamField body="audience" type="string" required>One of `all_affiliates`, `groups`, or `products`.</ParamField>
<ParamField body="description" type="string | null">Optional description.</ParamField>
<ParamField body="group_ids" type="array">Required for `groups`; not allowed for other audiences.</ParamField>
<ParamField body="product_ids" type="array">Required for `products`; not allowed for other audiences.</ParamField>
<ParamField body="is_active" type="boolean">Whether the URL is available. Defaults to `true`.</ParamField>
<ParamField body="sort_order" type="integer">Non-negative selection priority. Defaults to `0`.</ParamField>

## Response

Returns the created promotion URL. See [List Promotion URLs](/api/endpoint/program/list-promotion-urls) for the response object.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.affonso.io/v1/program/promotion-urls" \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Enterprise landing page",
      "url": "https://acme.com/enterprise",
      "audience": "groups",
      "group_ids": ["group_enterprise"],
      "sort_order": 10
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "promotion_url_abc123",
      "name": "Enterprise landing page",
      "url": "https://acme.com/enterprise",
      "description": null,
      "audience": "groups",
      "group_ids": ["group_enterprise"],
      "product_ids": [],
      "is_active": true,
      "sort_order": 10,
      "is_program_default": false,
      "default_for_group_ids": [],
      "created_at": "2026-07-28T10:00:00.000Z",
      "updated_at": "2026-07-28T10:00:00.000Z"
    }
  }
  ```
</ResponseExample>