Button Links Api API
The Links Api API from Button — 1 operation(s) for links api.
OpenAPI Specification
openapi: 3.1.0
info:
title: billing-api Accounts Links Api API
version: '4'
description: Retrieve billing accounts and affiliate commission transactions across currencies.
servers:
- url: https://api.usebutton.com/v1/affiliation
security:
- sec0: []
tags:
- name: Links Api
paths:
/:
post:
summary: Generate a Link
description: Generate and return a fully attributable Button-wrapped link to the desired Retailer page by passing the full page URL or the affiliate tracking link.
operationId: generate-a-link
requestBody:
content:
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
description: The target destination URL, such as `https://example.com/products`.
experience:
properties:
btn_pub_user:
type: string
description: 'Your user''s unique identifier. Typically a user ID or a stable hash of one. This value will be passed back to you in webhook requests associated with that downstream Brand activity. Must be a string between 1 and 255 characters long in the ASCII range [0x21-0x7E]. Note: Loyalty Publishers must include this value in order to know which user to reward.'
btn_pub_ref:
type: string
description: A Publisher reference value (e.g. click ID, campaign ID) that can be used to associate any value with any downstream Brand activity such as orders, app-installs, etc. This value will be passed back to you in webhook requests associated with that downstream Brand activity. String with a maximum length of 512.
btn_desktop_url:
type: string
description: A url to redirect to if the user is on desktop. If unset, the target flow is executed.
type: object
description: Optional customizations for the linking experience.
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"meta\": {\n \"status\": \"ok\"\n },\n \"object\":{\n \"merchant_id\": \"org-YYY\",\n \"affiliate\": null,\n \"links\": {\n \"universal\": \"https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brand123.com&btn_pub_user=your-user-id&btn_pub_ref=your-publisher--reference&btn_ref=org-XXX\"\n }\n }\n}"
schema:
type: object
properties:
meta:
type: object
properties:
status:
type: string
example: ok
object:
type: object
properties:
merchant_id:
type: string
example: org-YYY
affiliate: {}
links:
type: object
properties:
universal:
type: string
example: https://r.bttn.io?btn_url=https%3A%2F%2Fwww.brand123.com&btn_pub_user=your-user-id&btn_pub_ref=your-publisher--reference&btn_ref=org-XXX
'401':
description: '401'
content:
application/json:
examples:
Result:
value: "{\n \"meta\": {\n \"status\": \"error\"\n },\n \"error\": {\n \"message\": \"Invalid api_key\"\n }\n}"
schema:
type: object
properties:
meta:
type: object
properties:
status:
type: string
example: error
error:
type: object
properties:
message:
type: string
example: Invalid api_key
'403':
description: '403'
content:
application/json:
examples:
Result:
value: "{\n \"meta\": {\n \"status\": \"error\"\n },\n \"error\": {\n \"message\": \"Not approved for link building\",\n \"type\": \"NoMerchantApproval\",\n \"details\": {\n \"merchant_id\": \"org-123\"\n }\n }\n}"
schema:
type: object
properties:
meta:
type: object
properties:
status:
type: string
example: error
error:
type: object
properties:
message:
type: string
example: Not approved for link building
type:
type: string
example: NoMerchantApproval
details:
type: object
properties:
merchant_id:
type: string
example: org-123
'404':
description: '404'
content:
application/json:
examples:
Result:
value: "{\n \"meta\": {\n \"status\": \"error\"\n },\n \"error\": {\n \"message\": \"Merchant could not be detected from the url\",\n \"type\": \"NoMerchantLinkSupport\"\n }\n}"
schema:
type: object
properties:
meta:
type: object
properties:
status:
type: string
example: error
error:
type: object
properties:
message:
type: string
example: Merchant could not be detected from the url
type:
type: string
example: NoMerchantLinkSupport
deprecated: false
x-readme:
code-samples:
- language: curl
code: "curl https://api.usebutton.com/v1/links \\\n -X POST \\\n -u YOUR_API_KEY: \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://www.brand123.com\",\n \"experience\": {\n \"btn_pub_user\": \"your-user-id\",\n \"btn_pub_ref\":\"your-publisher-reference\"\n }\n }'"
samples-languages:
- curl
tags:
- Links Api
components:
securitySchemes:
sec0:
type: http
scheme: basic