Button Links API
Generate fully attributable Button-wrapped links to a Retailer page from a destination URL or affiliate tracking link.
OpenAPI Specification
{
"openapi": "3.1.0",
"info": {
"title": "links-api",
"version": "4",
"description": "Generate fully attributable Button-wrapped links to Retailer pages."
},
"servers": [
{
"url": "https://api.usebutton.com/v1/links"
}
],
"security": [
{
"sec0": []
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "http",
"scheme": "basic"
}
}
},
"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"
]
}
}
}
}
}