Affiliates

Fields summary

Field

Type

Read

Write

Filter

Order

Default

Req. for new

id

primary

int

name

email

string

status

enum

list

Draft

email

email

string

phone

string

string

address

object

create_date

datetime

range

now

account_manager_id

users.id | null

int

sales_manager_id

users.id | null

int

null

net

enum

list

Net 30

billing_frequency

enum

list

Monthly

stats_type

enum

list

Tracking

vat_rate_id

var-rates.id | 0

int

0

sps_id

string

null

Available options

Field: status

Current state of Affiliate. You can change it only via API methods.

Option

Description

Active

Affiliate is ready to work.

Draft

Manager have to check and activate the Affiliate.

Blocked

Affiliate was blocked and does not work temporarily.

Deleted

Affiliate was deleted and is not visible in web UI.

Field: net

Payment term

Option

Description

Net 7

Written on an invoice to show that it must be paid within 7 days

Net 10

Written on an invoice to show that it must be paid within 10 days

Net 15

Written on an invoice to show that it must be paid within 15 days

Net 30

Written on an invoice to show that it must be paid within 30 days

Net 45

Written on an invoice to show that it must be paid within 45 days

Net 60

Written on an invoice to show that it must be paid within 60 days

Net 90

Written on an invoice to show that it must be paid within 90 days

Field: billing_frequency

Relevant only if stats_type is Tracking.

Option

Description

None

Disable

Weekly

Item8 creates Bills weekly for the previous week.

Bi-Monthly

Item8 creates Bills twice a month: for the first and the second half of month (1-15; 16-last day)

Monthly

Item8 creates Bills monthly.

Field: stats_type

Source of billing statistics: tracking system or custom statistics entered manually.

Option

Description

Tracking

Item8 automatically creates Bills basing on tracking statistics. The billing period is taken from billing_frequency

Custom

Statistics (conversions) can be uploaded to item8 by API but manager have to create Bills manually.

Complex fields

Field: address

Address of person/company.

Key

Required

Type

Description

address[Country]

string

Name/code of country

address[State]

string

Name/code of state/region

address[City]

string

City name

address[Street]

string

Address - street and house number

address[Postcode]

string

Postcode (zipcode)

get
Filter

https://api.CLIENT_ID.item8.io/v1/vendors
You can use filter conditions. See fields table above and documentation about item8 filters.
Request
Response
Headers
Item8-Api-Key
required
string
Authentication API key.
Query Parameters
filter
optional
object
Filter conditions. See field map above.
pagination
optional
object
Limit and page of filter result.
order
optional
object
Order by some field (asc|desc). See field map above.
200: OK
List of objects found in item8 by filter conditions. "data" will be empty if no objects match the conditions.
{
"status": "success",
"message": "",
"data": [
{
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
]
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to filter action.",
"data": []
}

get
Get by ID

https://api.CLIENT_ID.item8.io/v1/vendors/:id
Find any vendor by id.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
200: OK
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to Vendor.",
"data": []
}
404: Not Found
If vendor doesn't exist.
{
"status": "error",
"message": "Vendor with id=42 not found.",
"data": []
}

post
Create

https://api.CLIENT_ID.item8.io/v1/vendors
Request to create new vendor in item8.
Request
Response
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
name
required
string
Affiliate person/company name.
email
required
string
Affiliate email for notification
phone
optional
string
Contact phone.
address
optional
object
Address of person/company. Use only available keys, see above.
account_manager_id
required
string
Network employee assigned as Affiliate's account manager. Account manager works with Affiliate's conversions, Bills, agreements, legal entities and receives email notifications about them.
sales_manager_id
optional
string
Network employee assigned as Affiliate's sales manager. Sales manager works with Affiliate's agreements, legal entities and receives email notifications about them.
net
optional
string
Payment term. Use only available options, see above.
billing_frequency
optional
string
Relevant only if stats_type is Tracking. Use only available options, see above.
stats_type
optional
string
Source of billing statistics: tracking system or custom statistics entered manually. Use only available options, see above.
vat_rate_id
optional
string
Foreign key to vat rate ID.
sps_id
optional
string
Unique Affiliate ID in your tracking system.
200: OK
Vendor has been created and you get the data as it is stored in item8.
{
"status": "success",
"message": "New vendor created.",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to create action.",
"data": []
}

put
Update

https://api.CLIENT_ID.item8.io/v1/vendors/:id
Request to update existing vendor in item8.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
name
optional
string
Affiliate person/company name.
email
optional
string
Affiliate email for notification
phone
optional
string
Contact phone.
address
optional
object
Address of person/company. Use only available keys, see above.
account_manager_id
optional
string
Network employee assigned as Affiliate's account manager. Account manager works with Affiliate's conversions, Bills, agreements, legal entities and receives email notifications about them.
sales_manager_id
optional
string
Network employee assigned as Affiliate's sales manager. Sales manager works with Affiliate's agreements, legal entities and receives email notifications about them.
net
optional
string
Payment term. Use only available options, see above.
billing_frequency
optional
string
Relevant only if stats_type is Tracking. Use only available options, see above.
stats_type
optional
string
Source of billing statistics: tracking system or custom statistics entered manually. Use only available options, see above.
vat_rate_id
optional
string
Foreign key to vat rate ID.
sps_id
optional
string
Unique Affiliate ID in your tracking system.
200: OK
Vendor has been updated and you get data as it is stored in item8.
{
"status": "success",
"message": "Vendor updated successfully.",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to update action.",
"data": []
}
500: Internal Server Error
Validator finds some problem in your request.
{
"status": "error",
"message": "Email is not valid.",
"data": []
}

put
Block

https://api.CLIENT_ID.item8.io/v1/vendors/:id/block
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
reason
optional
string
Reason why you block the Affiliate. Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Affiliate blocked.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
}

put
Unblock

https://api.CLIENT_ID.item8.io/v1/vendors/:id/unblock
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
reason
optional
string
Reason why you unblock the Affiliate. Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Affiliate unblocked.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
}

put
Activate

https://api.CLIENT_ID.item8.io/v1/vendors/:id/activate
Move Affiliate from Draft to Active status.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
200: OK
Affiliate activated and ready to work.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
}

put
Restore

https://api.CLIENT_ID.item8.io/v1/vendors/:id/restore
Move Affiliate from Deleted to Draft status.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
reason
optional
string
Reason why you restore Affiliate from deleted. Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Affiliate restored.
{
"status": "success",
"message": "",
"data": {
"id": 42,
"name": "Advert Industries Ltd.",
"status": "Draft",
"email": "john.smith@example.com",
"phone": "(888) 555-7238",
"address": {
"Street": "439 Karley Loaf Suite 897",
"City": "West Judge",
"Country": "USA",
"State": "NewMexico",
"Postcode": "17916"
},
"create_date": "2017-12-30 23:59:59",
"account_manager_id": 3,
"sales_manager_id": 2,
"net": "Net 30",
"billing_frequency": "Bi-Monthly",
"stats_type": "Tracking",
"vat_rate_id": 5,
"sps_id": "1q2w3e4r5t6y"
}
}

delete
Delete

https://api.CLIENT_ID.item8.io/v1/vendors/:id
Delete existing vendor from item8.
Request
Response
Path Parameters
id
required
int
Unique primary identifier of item8 object.
Headers
Item8-Api-Key
required
string
Authentication API key.
Form Data Parameters
reason
optional
string
Reason why you delete vendor Item8 saves the message in history. It should be empty or minimum 6 chars.
200: OK
Vendor has been deleted.
{
"status": "success",
"message": "Vendor deleted successfully.",
"data": []
}
403: Forbidden
If you don't have an access.
{
"status": "forbidden",
"message": "You don't have an access to delete action.",
"data": []
}
500: Internal Server Error
if validator finds some problem in your request.
{
"status": "error",
"message": "Message of reason should be minimum 6 letters.",
"data": []
}