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