Create a short link

Use this endpoint to create a Joylink short link from a destination URL. The API may apply affiliate rewrites before the short link is created, so the final destination is not always identical to the destination you send.

Request body

destination (required): URL to shorten.
trackingid (optional): Explicit affiliate tracking value. For Amazon links, this always overrides any existing tag query parameter on the destination.
require_choices (optional): When true, the API returns 409 choice_required instead of using the default override behavior for supported conflicts.
choices (optional): Map of choice ids to selected option ids. Use this when your integration already knows how it wants to resolve a conflict.
sub_id2 and sub_id3 (optional): Impact SubID values. These are applied only when the final destination is an Impact affiliate URL. Omit a field to preserve an existing value, or send an empty string to clear it.

Default behavior

When you do not send require_choices: true, the API resolves supported conflicts automatically:

The API starts with the destination you send.
If that destination is already an Impact affiliate link for a supported retailer, and your Joylink account has synced Impact tracking for that retailer, the API rewrites the link to use your tracking by default.
If the final destination is an Impact affiliate URL, sub_id2 and sub_id3 are applied after the Impact keep or override decision.
For Amazon URLs:
- trackingid always wins and replaces any existing tag.
- If trackingid is omitted, Joylink uses the Amazon tag configured in your Joylink user settings.
If the product has a Creator Connections campaign available, the API uses that Creator Connections link by default.
If there is no Creator Connections campaign, but a JL extra commission link is available, the API uses that extra commission link by default.

Creator Connections takes precedence over JL extra commission when both could apply.

Choice required

When require_choices is true, the API returns a 409 response with a reusable choice_required envelope instead of taking the default override path. The endpoint evaluates conflicts one at a time, in this order:

impact_link_override
amazon_tag_override
creator_connections_link_override
jl_extra_commission_link_override

If more than one conflict applies, re-send the same request with the returned choice populated in choices, and the API may return another 409 for the next conflict in the sequence. Supported conflicts:

An Impact affiliate link that would otherwise be rewritten to use your synced Impact tracking.
An Amazon link whose existing tag differs from your Joylink user tag when trackingid is omitted.
A product with an available Creator Connections campaign that would otherwise replace the original destination.
A product with an available JL extra commission link that would otherwise replace the original destination.

choice_required.options[].url is included when the API can preview the resulting destination ahead of time. Keep options always include it. Override options for Creator Connections and JL extra commission may omit it. Example Impact conflict:

{
  "choice_required": {
    "id": "impact_link_override",
    "prompt": "This link already uses an Impact affiliate tag. Choose whether to override it with your own affiliate tracking.",
    "documentation_url": "https://docs.joylink.io/create-a-short-link#choice-required",
    "options": [
      {
        "id": "override",
        "label": "Override with my affiliate tracking",
        "url": "https://goto.walmart.com/12345/..."
      },
      {
        "id": "keep",
        "label": "Keep the existing link",
        "url": "https://goto.walmart.com/54321/..."
      }
    ]
  }
}

For this Impact conflict:

override replaces the existing Impact affiliate link with the affiliate tracking configured on your Joylink account.
keep preserves the original affiliate destination instead of replacing it.

The documentation_url field points to this section so an integration can surface a helpful link when it receives the conflict. Example Amazon conflict:

{
  "choice_required": {
    "id": "amazon_tag_override",
    "prompt": "This Amazon link already uses a different affiliate tag. Choose whether to override it with your own affiliate tracking.",
    "documentation_url": "https://docs.joylink.io/create-a-short-link#choice-required",
    "options": [
      {
        "id": "override",
        "label": "Override with my affiliate tracking",
        "url": "https://www.amazon.com/dp/B0TEST1234?tag=my-tag-20"
      },
      {
        "id": "keep",
        "label": "Keep the existing link",
        "url": "https://www.amazon.com/dp/B0TEST1234?tag=other-tag-20"
      }
    ]
  }
}

For this Amazon conflict:

override replaces the existing Amazon tag with your Joylink user tag.
keep preserves the original Amazon tag already present on the destination URL.

Example Creator Connections conflict:

{
  "choice_required": {
    "id": "creator_connections_link_override",
    "prompt": "This product has a Creator Connections campaign available. Choose whether to override the destination with the Creator Connections link.",
    "documentation_url": "https://docs.joylink.io/create-a-short-link#choice-required",
    "options": [
      {
        "id": "override",
        "label": "Override with Creator Connections"
      },
      {
        "id": "keep",
        "label": "Keep the existing link",
        "url": "https://www.amazon.com/dp/B0TEST1234?tag=my-tag-20"
      }
    ]
  }
}

For this Creator Connections conflict:

override uses the Creator Connections link that would normally be applied for this product.
keep preserves the original destination and skips the Creator Connections link rewrite.

Example JL extra commission conflict:

{
  "choice_required": {
    "id": "jl_extra_commission_link_override",
    "prompt": "This product has a JL extra commission link available. Choose whether to override the destination with the JL extra commission link.",
    "documentation_url": "https://docs.joylink.io/create-a-short-link#choice-required",
    "options": [
      {
        "id": "override",
        "label": "Override with JL extra commission link"
      },
      {
        "id": "keep",
        "label": "Keep the existing link",
        "url": "https://www.amazon.com/dp/B0TEST1234?tag=my-tag-20"
      }
    ]
  }
}

For this JL extra commission conflict:

override uses the JL extra commission link that would normally be applied for this product.
keep preserves the original destination and skips the extra commission link rewrite.

Choose the behavior up front

If your integration already knows how it wants to handle this conflict, send the choice up front in the choices object. Example request that uses the default override behavior:

{
  "destination": "https://goto.walmart.com/..."
}

Send an explicit override choice when you want to be fully declarative:

{
  "destination": "https://goto.walmart.com/...",
  "choices": {
    "impact_link_override": "override"
  }
}

To preserve the original affiliate destination instead, send:

{
  "destination": "https://goto.walmart.com/...",
  "choices": {
    "impact_link_override": "keep"
  }
}

For an Amazon link with no trackingid, preserve the existing Amazon tag with:

{
  "destination": "https://www.amazon.com/dp/B0TEST1234?tag=other-tag-20",
  "choices": {
    "amazon_tag_override": "keep"
  }
}

If a JL extra commission product is available and you want to keep the original destination, send:

{
  "destination": "https://www.amazon.com/dp/B0TEST1234?tag=my-tag-20",
  "choices": {
    "jl_extra_commission_link_override": "keep"
  }
}

If a Creator Connections campaign is available and you want to keep the original destination, send:

{
  "destination": "https://www.amazon.com/dp/B0TEST1234?tag=my-tag-20",
  "choices": {
    "creator_connections_link_override": "keep"
  }
}

To opt into the 409 flow, send:

{
  "destination": "https://goto.walmart.com/...",
  "require_choices": true
}

Authorizations

X-API-Key

string

header

required

Body

application/json

destination

string

required

URL to shorten. This is the starting destination before any affiliate rewrites are applied.

Example:

"https://www.amazon.com/dp/B0TEST1234?tag=other-tag-20"

trackingid

string

Optional explicit affiliate tracking value. For Amazon links, sending this always overrides any existing tag query parameter on the destination.

Example:

"my-tag-20"

require_choices

boolean

When true, the API returns 409 choice_required instead of using the default override behavior for supported conflicts. Conflicts are evaluated one at a time in this order: impact_link_override, amazon_tag_override, creator_connections_link_override, jl_extra_commission_link_override.

Example:

false

sub_id2

string

Optional Impact SubID2 value. Applied only when the final destination is an Impact affiliate URL. Omit to preserve an existing value, or send an empty string to clear it.

Example:

"campaign-42"

sub_id3

string

Optional Impact SubID3 value. Applied only when the final destination is an Impact affiliate URL. Omit to preserve an existing value, or send an empty string to clear it.

Example:

"post-99"

choices

object

Optional map of choice_required ids to selected option ids. Use override to accept Joylink's default rewrite, or keep to preserve the original value or destination for the returned conflict.

Show child attributes

Example:

{ "impact_link_override": "keep" }

Response

Successfully created short link

url

string

required

The generated short URL.

Example:

"https://joylink.io/abc123"

Getting Started

Endpoints

Create a short link

Request body

Default behavior

Choice required

Choose the behavior up front

Authorizations

Body

Response

​Request body

​Default behavior

​Choice required

​Choose the behavior up front

Authorizations

Body

Response

Request body

Default behavior

Choice required

Choose the behavior up front