SOAP API Documentation

This page documents the legacy SOAP API feature which is deprecated as of v1.8.10.0 of MageRewards for Magento and will no longer be maintained.

See the new REST API feature of MageRewards for Magento instead.

Outline

Introduction

The MageRewards API allows a remote interface for authorized external sources to access MageRewards data. You can use this to integrate MageRewards with third party applications which are not necessarily using the Magento system.

This API package is based on SOAP technology version 1.2, supported as of Magento Community 1.3.  Read more about support in Magento 1.x.

Setup

  1. In the Magento back-end > System > Web Services you will have to create a new Web Services role. If you already have a role for other purposes, you can also just modify it so that it implements the MageRewards access level.
  2. Make sure that a web services user has access to the above created/modified role.
  3. Use your own coding web services to connect to the Magento service
    • http://<your_website_url>/api/?wsdl
      		
      Or if you're using soap and SOAP is not default
      http://<your_website_url>/api/soap/?wsdl
      		
  4. Web service calls will be rewards functions. So to call the getbalancebyemail function you would do something like:
    • rewards.getbalancebyemail
      		

API Functions

Fetching Functions

These functions will retrieve data from the MageRewards data center.

getcustomeridbyemail

Description: Fetches a customer's Magento (entity) ID by e-mail and website id.

  • Parameter #1: Customer's e-mail address
    Example:  johnmccay__123@magento.com
  • Parameter #2: Website ID
  • Return Result: Returns an integer value representing the customer's Magento (entity) ID.
getbalancebyemail

Description: Fetches a customer's USABLE points balance for a particular customer by e-mail and website id.
Parameters:

  • Parameter #1: Customer's e-mail address
  • Parameter #2: Website ID

Return Result: Returns an array/map where the key is the points currency id and the value is the number of points. PHP Example: array([1] => 1233) JSON Example: [1: 1233]

getbalancebyid

Description: Fetches a customer's USABLE points balance for a particular customer by the customer's Magento (entity) ID.

  • Parameter #1: Customer's ID
  • Return Result: The return results are identical to the getbalancebyemail function
list

Description: Fetches a list of all transfers made

  • Parameter #1: Date filters (optional)

By default, all transfers are fetched. You can, however, fetch only the transfers that were created or updated after a certain date. Please check out some of the   sample codes for an example on how to set the date

  • Parameter #2: Page Size (optional)

Using this parameter you can limit the number of transfers fetched.

  • Return Result: Returns an array with 2 items:

totalRecords - contains the total number of transfers found

items - contains an array with all the items found that match the parameters

Altering Functions

These functions will alter MageRewards data in some way. (also known as Mutator methods)

maketransfer

Description: Creates a points transfer for a customer that may reduce or increase the customer's points balance.

  • Parameter #1: Customer's ID
  • Parameter #2: Points currency ID
    If you don't have more than one points currency ID and/or you are using MageRewards 1.2.9.2 or less, your points currency id is probably "1". You can also check this by going into the MageRewards points currency management screen in the Magento back-end admin panel
  • Parameter #3: Points quantity
    How many points do you want to transfer? If this is a negative value points will be deducted from the balance. This value must also not be equal to 0.
  • Parameter #4: Transfer comments (optional)
    Optionally enter in some comments that will appear to the customer in their transfer history, as well as to any administrators in the Magento back-end.
  • Parameter #5: Transfer Status ID (optional)
  • Parameter #6: Transfer Reason ID (optional)
  • Return Result: No value returned. If no error occurred that means that the transfer was successful.

Sample Code

Language: PHP 
Description: Fetches the points balance for a particular customer in the points currency '1' and website '1' and outputs the results to the screen, then ends the session.

$client = new SoapClient('http://YOURWEBSITEURL.COM/api/soap/?wsdl');
$session = $client->login('test', '123456'); // these are your API client credentials configured in the Magento back-end.
$result = $client->call($session, 'rewards.getbalancebyemail', array('CUSTOMER@EMAIL.COM', '1'));
echo "The customer CUSTOMER@EMAIL.COM at website #1 has {$result[1]} points";
// If you don't need the session anymore
$client->endSession($session);<br>
	

Language: PHP 
Description: Transfers 100 points (points currency 1) to a customer.

$client = new SoapClient('http://YOURWEBSITEURL.COM/api/soap/?wsdl');
$session = $client->login('test', '123456');
$result = $client->call($session, 'rewards.maketransfer', array($customerId, 1, 100, "Test distribution from API2") );
// If you don't need the session anymore
$client->endSession($session);<br>
	

Language: PHP 
Description: Reduces 100 points (points currency 1) from a customer.

$client = new SoapClient('http://YOURWEBSITEURL.COM/api/soap/?wsdl');
$session = $client->login('test', '123456');
$result = $client->call($session, 'rewards.maketransfer', array($customerId, 1, -100, "Test transfer from API2") );
// If you don't need the session anymore
$client->endSession($session);<br>
	

Language: PHP 
Description: Fetch 15 transfers that were created or updated after 2015.05.20.

$client = new SoapClient('http://YOURWEBSITEURL.COM/api/soap/?wsdl');
$session = $client->login('test', '123456');
$dateLimitation = '2015-05-18';
$pageSize = 15;
$result = $client->call($session, 'rewards.list', array(
	array('updated_at' => array ('from' => $dateLimitation )),
	$pageSize
));
var_dump($result);
// If you don't need the session anymore
$client->endSession($session);
	

Troubleshooting

I get a fatal error trying to use $client->call($session_id, 'rewards.getcustomeridbyemail'

If you're using the API and trying something like this:

    $cid = $client->call($session_id, 'rewards.getcustomeridbyemail', array('blah@blahblah.com','1') )
	

and you get this error:

    Fatal error: Call to a member function call() on a non-object in /.../ on line **
	

then you are probably not setting a proper session_id in the initial instantiation of the $client object and/or the session ID is not valid.

I get a 404 error when trying to do run YOURWEBSITEURL.COM/api/soap/?wsdl in my browser

That probably means that your store does not have apache rewrites enabled or available for use. Instead try  http://YOURWEBSITEURL.COM/index.php/api/soap/?wsdl.

Still need help? Get Help Get Help