Refersion Affiliates API
Create, retrieve, update, search, and manage affiliate accounts and their conversion triggers.
OpenAPI Specification
openapi: 3.0.0
info:
title: Refersion REST Affiliates API
version: '2.0'
description: 'The Refersion REST API v2 is organized around REST, with predictable resource-oriented URLs and HTTP response codes to indicate errors. Valid JSON is returned in all responses, including errors. The API allows you to automate affiliate and conversion approval workflows, generate real-time performance reports, and integrate Refersion into existing e-commerce platforms such as Shopify, BigCommerce, and WooCommerce.
'
contact:
name: Refersion Inc
email: helpme@refersion.com
url: https://www.refersion.com
termsOfService: https://www.refersion.com/terms
servers:
- url: https://api.refersion.com/v2
tags:
- name: Affiliates
description: Create, retrieve, update, search, and manage affiliate accounts and their conversion triggers.
paths:
/affiliate/new:
post:
operationId: new_affiliate
summary: New Affiliate
description: 'Create a new affiliate. Returns the affiliate ID and their referral link. Tip: Save the id from the response to map your user to their affiliate account in Refersion.
'
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
description: If you want to send custom fields, please contact Refersion support.
required: true
content:
application/json:
schema:
type: object
required:
- first_name
- last_name
- email
- password
- status
properties:
offer:
type: string
description: Specific Offer ID to opt affiliate into; defaults to your default offer.
example: '12345'
first_name:
type: string
description: The affiliate's first name.
example: Bill
last_name:
type: string
description: The affiliate's last name.
example: Smith
email:
type: string
description: Must be a valid email address.
example: testing@refersion.com
password:
type: string
description: 'Minimum 9 characters, maximum 72 characters, at least 1 uppercase letter, 1 lowercase letter, 1 number, and 1 special character. Cannot match the affiliate''s email.
'
example: Secure!Pass1
company:
type: string
description: Company name.
paypal_email:
type: string
description: PayPal email address for commission payments.
address1:
type: string
address2:
type: string
city:
type: string
zip:
type: string
country:
type: string
minLength: 2
maxLength: 2
description: Two-letter ISO country code (e.g. US, GB, CA).
example: US
state:
type: string
description: State or province.
phone:
type: string
send_welcome:
type: string
enum:
- 'TRUE'
- 'FALSE'
default: 'FALSE'
description: Whether Refersion should send a welcome email.
status:
type: string
enum:
- ACTIVE
- PENDING
default: PENDING
description: Initial affiliate status.
example: ACTIVE
conversion_trigger_coupon:
type: string
description: A unique coupon code to assign to this affiliate as a conversion trigger.
example: BILLSMITH10
unique_merchant_id:
type: string
description: Optional alphanumeric identifier for internal use.
example: abc123
responses:
'200':
description: Affiliate created successfully.
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The affiliate's unique code.
link:
type: string
description: The affiliate's referral link.
message:
type: string
examples:
response:
value:
id: a3y7
link: https://site.refersion.com/c/a3y7
message: The affiliate 37569297 has been created with the status of ACTIVE.
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
/affiliate/get:
post:
operationId: get_affiliate
summary: Get Affiliate
description: Get information about an affiliate by their ID or affiliate code.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
properties:
id:
type: integer
description: The affiliate's numeric ID.
example: 12345678
- type: object
properties:
affiliate_code:
type: string
description: The Refersion affiliate code returned when creating an affiliate.
example: a3y7
responses:
'200':
description: Affiliate details returned.
content:
application/json:
schema:
type: object
properties:
id:
type: string
offer_id:
type: string
status:
type: string
first_name:
type: string
last_name:
type: string
company_name:
type: string
email:
type: string
link:
type: string
custom_fields:
type: array
items:
type: object
properties:
label:
type: string
value:
type: string
examples:
response:
value:
id: 37567438
offer_id: '1234'
status: ACTIVE
first_name: Bill
last_name: Smith
company_name: Company
email: testing@refersion.com
link: https://site.refersion.com/c/a3y7
custom_fields:
- label: What is your web site?
value: https://www.refersion.com
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
/affiliate/edit:
post:
operationId: edit_affiliate
summary: Edit Affiliate
description: 'Edit existing affiliates. Returns all successfully updated affiliate IDs. Always check ids_changed in the response. At least 1 field besides id must be provided per affiliate.
'
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
affiliates:
type: array
items:
type: object
required:
- id
properties:
id:
type: integer
description: The affiliate's numeric ID.
example: 12345678
offer:
type: number
description: Offer ID to move the affiliate into.
example: 12345
first_name:
type: string
example: Jane
last_name:
type: string
example: Doe
email:
type: string
example: name@email.com
paypal_email:
type: string
example: name@email.com
company:
type: string
example: Acme, Inc.
address1:
type: string
address2:
type: string
city:
type: string
state:
type: string
example: NY
zip:
type: string
country:
type: string
example: US
phone:
type: string
custom_fields:
type: array
items:
type: object
description: Array of objects keyed by custom field ID.
responses:
'200':
description: Affiliate update results.
content:
application/json:
schema:
type: object
properties:
ids_changed:
type: array
items:
type: integer
ids_not_changed:
type: array
items:
type: integer
examples:
response:
value:
ids_changed:
- 1
- 3
ids_not_changed:
- 2
- 4
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
/affiliate/list:
post:
operationId: list_affiliates
summary: List All Affiliates
description: Get all affiliates in your account with pagination support (max 100 per call).
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
content:
application/json:
schema:
type: object
properties:
limit:
type: string
description: Number of results to return per call. Maximum 100.
example: '3'
default: '3'
page:
type: string
description: Page offset for pagination.
example: '1'
default: '1'
responses:
'200':
description: Paginated list of affiliates.
content:
application/json:
schema:
type: object
properties:
total:
type: integer
description: Total number of affiliates.
results:
type: array
items:
type: object
properties:
id:
type: string
offer_id:
type: string
status:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
custom_fields:
type: array
items:
type: object
properties:
label:
type: string
value:
type: string
examples:
response:
value:
total: 3
results:
- id: 694c
offer_id: '1234'
status: ACTIVE
first_name: Barbara
last_name: Verde
email: testing1@refersion.com
custom_fields: []
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
/affiliate/search:
post:
operationId: search_affiliates
summary: Search Affiliates
description: 'Find affiliates based on email address, affiliate ID, or name. Affiliate ID must be exact; email can be a partial match.
'
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- keyword
properties:
keyword:
type: string
description: Affiliate ID (exact) or partial email address to search for.
example: testing
first_name:
type: string
description: First name to search for.
example: Bill
last_name:
type: string
description: Last name to search for.
example: Smith
page:
type: string
description: Page offset.
example: '1'
default: '1'
responses:
'200':
description: Search results.
content:
application/json:
schema:
type: object
properties:
total:
type: integer
results:
type: array
items:
type: object
properties:
id:
type: string
description: The affiliate's code.
offer_id:
type: string
status:
type: string
description: PENDING, ACTIVE, DENIED, or DISABLED.
first_name:
type: string
last_name:
type: string
email:
type: string
custom_fields:
type: array
items:
type: object
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
/affiliate/status_change:
post:
operationId: affiliate_status_change
summary: Change Affiliates Status
description: Set a new status value for a list of affiliate IDs. Limit of 50 IDs per call.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- ids
- status
properties:
ids:
type: array
items:
type: integer
description: One or more affiliate IDs to change (max 50).
example:
- 1
- 2
- 3
- 4
status:
type: string
enum:
- ACTIVE
- DENIED
- DISABLED
description: The new status to set.
responses:
'200':
description: Affiliate status change results.
content:
application/json:
schema:
type: object
properties:
ids_changed:
type: array
items:
type: integer
ids_not_changed:
type: array
items:
type: integer
examples:
response:
value:
ids_changed:
- 1
- 3
ids_not_changed:
- 2
- 4
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
/affiliate/trigger:
post:
operationId: new_affiliate_trigger
summary: Create Conversion Trigger
description: Create a Conversion Trigger (coupon, SKU, or email) for a specific affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- affiliate_code
- type
- trigger
properties:
affiliate_code:
type: string
description: The Refersion affiliate identifier returned from /affiliate/new.
example: a3y7
type:
type: string
enum:
- COUPON
- SKU
- EMAIL
description: The type of conversion trigger.
trigger:
type: string
description: The trigger value (e.g. coupon code, email address, or SKU).
example: code100
responses:
'200':
description: Conversion trigger created.
content:
application/json:
schema:
type: object
properties:
trigger_id:
type: integer
trigger:
type: string
examples:
response:
value:
trigger_id: 1097
trigger: CODE100
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
/trigger/delete:
post:
operationId: delete_conversion_trigger
summary: Delete Conversion Triggers
description: Delete all conversion triggers passed in the body message and store the affiliate activity. Max 50 triggers per call.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/Refersion-Public-Key'
- $ref: '#/components/parameters/Refersion-Secret-Key'
- $ref: '#/components/parameters/Content-Type'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- affiliates
properties:
affiliates:
type: array
description: An array of conversion triggers to delete. Max 50.
items:
type: object
required:
- id
- trigger
- type
properties:
id:
type: integer
description: The affiliate's numeric ID.
example: 12345678
trigger:
type: string
description: The trigger value to delete (e.g. "JANEDOE10").
example: SKUNAME123
type:
type: string
enum:
- COUPON
- EMAIL
- SKU
description: The conversion trigger type.
responses:
'200':
description: Array of trigger IDs successfully deleted.
content:
application/json:
schema:
type: array
items:
type: integer
examples:
response:
value:
- 23213131
'400':
$ref: '#/components/responses/400_Error'
'401':
$ref: '#/components/responses/401_Error'
'404':
$ref: '#/components/responses/404_Error'
'422':
$ref: '#/components/responses/422_Error'
'429':
description: Too many conversion triggers in the affiliates object (max 50).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSingle'
components:
responses:
400_Error:
description: Missing required field in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSingle'
examples:
response:
value:
error: Missing required field X
401_Error:
description: Unauthorized – Your API keys are incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSingle'
examples:
response:
value:
error: Invalid API credentials (error 2).
422_Error:
description: Unprocessable Entity – The data you are sending has errors.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
404_Error:
description: Empty request body.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorSingle'
examples:
response:
value:
error: Bad request, no body
schemas:
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: string
ErrorSingle:
type: object
properties:
error:
type: string
parameters:
Refersion-Public-Key:
in: header
name: Refersion-Public-Key
required: true
schema:
type: string
example: pub_abc12300000000000000
description: Your Refersion public API key.
Refersion-Secret-Key:
in: header
name: Refersion-Secret-Key
required: true
schema:
type: string
example: sec_abc12300000000000000
description: Your Refersion secret API key.
Content-Type:
in: header
name: Content-Type
required: true
schema:
type: string
enum:
- application/json
default: application/json