Teilashare

This is an unofficial client library for the ShareaSale affiliate reporting API. It does not include the publisher API or any other APIs at the moment. Please see below for the supported endpoints as well as a required and optional parameters on each endpoint.

Installation

Add this line to your application's Gemfile:

gem 'teilashare'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install teilashare

Usage

Instantiate a client via:

credentials = {
  token: ENV['TOKEN'],
  api_secret: ENV['API_SECRET'],
  affiliate_id: ENV['affiliate_id']
}

client = Teilashare.new(credentials)

You can then request reports on this client via:

result = client.today_stats(format: 'xml')

Please refer to the Teilashare documentation for required and optional parameters for your desired report. The default format is CSV, but you can request XML format or pipe formatted data (PSV?) via the format option.

Activity Details

required params:

action
version
affiliateId
token
dateStart

optional

dateEnd
merchantId
lockDate,
paidDate
sortCol
sortDir
XMLFormat
xml_format

client.activity_details(
  start_date: '07-31-2020',
  end_date: '08-31-2020',
  merchant_id: 234234234
)

Activity Summary

required params:

action
version
affiliateId
token

optional params

merchantId Merchant Id Value
filterCol hits, sales, OR commissions
filterSpan month OR total
filterValue Number
sortCol hitsmonth, salesmonth, salestotal, commissionsmonth, commissionstotal, organization
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.activity_summary(sort_col: 'salestotal', sort_dir: 'asc')

Merchant Timespan Report

required params:

dateStart

optional params

dateEnd mm/dd/yyyy
merchantId Merchant Id Value
sortCol hits, grosssales, reversals, netsales, sales, mcredits, commissions
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

csv = client.merchant_timespan(date_start: '12/31/2020')

Today's Stats

required params

none

optional params

distinctlink 1 or 0
sortCol commissions, hits, sales
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.today_stats(
  distinct_link: 1,
  sort_col: 'commissions',
  sort_dir: 'asc'
)

Monthly Summary

required params

dateMonth mm/dd/yyyy

optional params

sortCol merchantId, commissionsum, salesum
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.monthly_summary(
  date_month: '12/01/2020',
  sort_col: 'commissions',
  sort_dir: 'asc'
)

Void Trail

required params

dateStart mm/dd/yyyy

optional params

dateEnd mm/dd/yyyy
merchantID Valid merchant ID.
XMLFormat 0 or 1
format pipe, xml, csv

client.void_trail(
  date_start: '12/01/2020'
)

Traffic

required params

dateStart

optional params

dateEnd mm/dd/yyyy
groupBy bannerID or afftrack
bannerID Valid bannerID value. MerchantID must also be specified when using this parameter. BannerType must also be specified when using this parameter.
afftrack Valid afftrack value. MerchantID must also be specified when using this parameter.
sortCol hits, commissions, numberOfSales, numberOfVoids, conversion, epc
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

conditionally required

bannerType Click for values.
merchantId Valid Merchant Id

client.traffic(
  date_start: '12/01/2020'
)

API Token Count

required params

optional params

XMLFormat 0 or 1
format pipe, xml, csv

client.api_token_count

Products

required params

keyword Word or Phrase

optional params

merchantId Valid Merchant Id
excludeMerchants List of Merchant Id
XMLFormat 0 or 1
format pipe, xml, csv

client.products(
  keyword: 'wool hats'
)

Invalid Links

required params

optional params

merchantIdList Comma delimited list of valid Merchant IDs
XMLFormat 0 or 1
format pipe, xml, csv

client.invalid_links(
  merchantIdList: 12342,1234234,234234
)

Order Inquiry

required params

merchantId Valid Merchant Id
orderDate mm/dd/yyyy
orderNumber Merchant's order number (alpha-numeric)

optional params

XMLFormat 0 or 1
format pipe, xml, csv

client.order_inquiry(
  merchant_id: 1234,
  order_date: '12/31/2020',
  order_number: abcdef234
)

Merchant Datafeeds

required params

optional params

blnMemberOf 1 or 0
blnNotMemberOf 1 or 0
category Click for values.
updateDate mm/dd/yyyy
keyword word or phrase
sortCol 7DayEpc, 30DayEpc, saleCommissionAmount, productcount, datafeedupdated, organization
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.merchant_datafeed

Coupon Deals

required params

optional params

current 1
modifiedSince mm/dd/yyyy
merchantId Valid Merchant Id number.
XMLFormat 0 or 1
format pipe, xml, csv

client.coupon_deal

Merchant Status

required params

optional params

merchantId List of Merchant Id
category Click for values.
programStatus online, offline, lowfunds, onlineNotLowFunds
keyword word or phrase
sortCol organization, salescommission, hitcommission, leadcommission, merchantStatus, category, applydate
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.merchant_status

Merchant Creatives

required params

optional params

sortCol bannerId, bannerHeight, bannerWidth, category, type
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

conditional params

merchantId Valid Merchant Id. Required unless modifiedDate is present.
modifiedDate Valid date no more than 31 days in the past. Required unless merchantID is present. Format MM/DD/YYYY

client.merchant_creative

Merchant Gift Cards

required params

optional params

sortCol giftcardId, publishdate, title, merchantId, organization
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.merchant_gift_cards

Edit Trail

required params

dateStart mm/dd/yyyy

optional params

dateEnd mm/dd/yyyy
merchantID Valid merchant ID.
XMLFormat 0 or 1
format pipe, xml, csv

client.edit_trail

Payment Summary

required params

paymentDate mm/dd/yyyy must be 20th of month in the last 12 months

optional params

sortCol organization, merchantID, commissions, numberofsales
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.payment_summary

Merchant Search

required params

optional params

Keyword Word or Phrase
Category Click for values.
activatedSince mm/dd/yyyy
-tjoined 1 or 0
datafeed 1 or 0
autodeposit 1 or 0
autoapprove 1 or 0
epc Any number
avgsale Any number
reversalrate Any number
cookielength Any Number
sortCol a7dayepc,a30dayepc,salecommission,leadcommission,hitcommission,organization,organization,startdate,cookielength,powerrank,relationshipID
sortDir asc or desc
XMLFormat 0 or 1
format pipe, xml, csv

client.merchant_search(keyword: 'wool')

Merchant Search by Product

required params

keyword Word or Phrase

optional params

-tjoined 1 or 0
merchantId Valid Merchant Id
excludeMerchants List of Merchant Id
XMLFormat 0 or 1
format pipe, xml, csv

client.merchant_search_by_product(keyword: 'shoes')

Ledger Report

required params

optional params

dateStart mm/dd/yyyy
dateEnd mm/dd/yyyy
includeOrderDetails 0 or 1
includeMerchantDetails 0 or 1
XMLFormat 0 or 1
format pipe, xml, csv

client.ledger_report

Balance Inquiry

required params

optional params

XMLFormat 0 or 1
format pipe, xml, csv

client.balance_inquiry

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

If you want to record API requests, you'll need to export environment variables in the format:

export TOKEN=abc
export AFFILIATE_ID=123456789
export API_SECRET=def
export API_VERSION=2.3

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tommycarney/partagerasale.

License

The gem is available as open source under the terms of the MIT License.