# Button Links

Button Links allow you to create a link that utilizes Button's routing and attribution systems to help a user shop in-app or on the web.

## Example

### Link Composition

#### Raw Link

```css
https://r.bttn.io? \
  btn_url={https%3A%2F%2Fwww.retailer.com} \
  &btn_pub_user={user_id_here} \
  &btn_ref={org-0000000000000000}
```

```css
https://r.bttn.io?btn_url=https%3A%2F%2Fwww.retailer.com&btn_pub_user=user-123&btn_ref=org-0000000000000000
```

### Query String Parameters

Button Links accept the following query string parameters. All links must only contain ASCII characters and have [properly encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding) query strings.

| Field         | Required?                          | Definition                                                                                                                                      |
|---------------|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `btn_url`    | Yes                                | The target destination URL (url-encoded, including https). This can be a retailer landing page or an affiliate tracking link, depending on whether Button manages your affiliate network accounts.<br>e.g., `https%3A%2F%2Fwww.retailer.com/p/12345` |
| `btn_ref`    | Yes                                | Your Button Organization ID (always starts with the prefix `org-`).<br>e.g., `org-0000000000000000`<br>This can be found in your [Button Dashboard](https://app.usebutton.com/settings/organization/developer).                         |
| `btn_pub_user`| Required for user rewards         | Your user’s unique identifier. This value will be passed back to you on any transaction webhook events associated with downstream conversions. Must be under 256 characters.<br>e.g., `user-12345`<br>_Note: If you reward users for shopping activity, you should include this value in order to know which user to reward._              |
| `btn_pub_ref`| No                                 | A unique publisher reference value (e.g. click ID, campaign ID).<br>This value will be passed back to you in webhook events associated with any downstream conversions activity. Must be under 512 characters (decoded).<br>e.g., `click-abc123`                                            |

## Passthrough Values

Similar to how publishers can leverage Button's Publisher SDK to persist values across taps and conversion events, publishers can pass a user ID or unique publisher reference value directly on Button Links.

Simply add the `btn_pub_user` parameter to pass through your user's unique identifier, or add the `btn_pub_ref` parameter to pass through your unique publisher reference (e.g., click ID, campaign ID).

### Example Button Link

#### Link Composition

##### Raw Link

```css
https://r.bttn.io? \
  btn_ref={org-0000000000000000} \
  &btn_url={https%3A%2F%2Fwww.retailer.com} \
  &btn_pub_user={user_id_here} \
  &btn_pub_ref={your_passthrough_value}
```

```css
https://r.bttn.io?btn_ref=org-0000000000000000&btn_url=https%3A%2F%2Fwww.retailer.com&btn_pub_user=user-123&btn_pub_ref=your-ref
```

## Leveraging Button Links via API

- [Generate a Link](https://developer.usebutton.com/update/reference/generate-a-link-2) — the Button Links API can be used to generate Button Links via an API call.

Updated 27 days ago