REST API: Resources

This page documents the REST API feature available as of v1.8.10.0 of MageRewards for Magento.
Documentation for the deprecated SOAP API feature, can be found here.

Outline

Resources

Similar to Magento, all resource end-points are accessible using a URL like this:
http://{{magentohost}}/api/rest/{{resource}}/
Available resources include:

rewards_transfers

This represents a rewards transaction belonging to a customer account. It maps to the rewards/transfer data models in Magento.
End-points include:

GET /rewards_transfers
URL Structure http://{{magentohost}}/api/rest/rewards_transfers/
Description Allows user to retrieve a list of existing rewards_transfer objects
Notes Only Admin user can retrieve the list of transfers
Authentication Admin
Optional Parameters:
Note:

If the attribute value consists of several words separated by a whitespace, the %20 sign is used.
For example:
/api/rest/rewards_transfer?filter[1][attribute]=updated_by&filter[1][in]=John%20Smith

Response

Response will be an array of zero or more objects of type rewards_transfer.
Sample Response:
    [
      {
        "rewards_transfer_id": "12730",
        "customer_id": "362",
        "quantity": 500,
        "comments": "[DEVELOPER MODE] ",
        "effective_start": "2015-05-29 11:34:01",
        "reason_id": "6",
        "issued_by": "",
        "is_dev_mode": true,
        "status_id": "5",
        "created_at": "2015-05-27 18:08:46",
        "updated_at": "2015-05-27 18:08:46",
        "updated_by": "Mohsen Hadianfard"
      },
      {
        "rewards_transfer_id": "110560",
        "customer_id": "1214",
        "quantity": 500,
        "comments": "Jus Because",
        "effective_start": "2016-05-12 05:00:03",
        "reason_id": "6",
        "issued_by": "",
        "is_dev_mode": false,
        "status_id": "5",
        "created_at": "2016-05-12 03:00:03",
        "updated_at": "2016-05-12 03:00:03",
        "updated_by": "Mohsen Hadianfard"
      },
      {
        "rewards_transfer_id": "110529",
        "customer_id": "1",
        "quantity": 600,
        "comments": null,
        "effective_start": "2016-05-04 06:34:22",
        "reason_id": "6",
        "issued_by": "",
        "is_dev_mode": false,
        "status_id": "5",
        "created_at": "2016-05-04 04:34:22",
        "updated_at": "2016-05-04 04:34:22",
        "updated_by": "Mohsen Hadianfard"
      },
      {
        "rewards_transfer_id": "12749",
        "customer_id": "364",
        "quantity": 1000,
        "comments": null,
        "effective_start": "2015-06-04 12:08:51",
        "reason_id": "6",
        "issued_by": "",
        "is_dev_mode": false,
        "status_id": "5",
        "created_at": "2015-06-04 16:08:51",
        "updated_at": "2015-06-04 16:08:51",
        "updated_by": "Mohsen Hadianfard"
      }
    ]
	
POST /rewards_transfers
URL Structure http://{{magentohost}}/api/rest/rewards_transfers/
Description Allows you to create a new rewards_transfer object
Notes Only Admin user can create a new transfer
Authentication Admin
Parameters:

Response

If the transfer was created successfully, you'll receive HTTP Response Code = 200 with empty Body and Location header like /api/rest/rewards_transfers/555 where 555 is the rewards_transfer_id of the new transfer.
GET /rewards_transfers/:rewards_transfer_id
URL Structure http://{{magentohost}}/api/rest/rewards_transfers/{{rewards_transfer_id}}
Description Allows retrieval of a specific transfer object.
Notes Only Admin user can retrieve a transfer
Authentication Admin
Parameters none
Response

If object is found, a json response will look like this:

    {
      "rewards_transfer_id": "114927",
      "customer_id": "6",
      "quantity": 5,
      "comments": "Points transfer created through API",
      "effective_start": "2016-08-09 16:19:36",
      "reason_id": "845",
      "issued_by": "",
      "is_dev_mode": false,
      "status_id": "4",
      "created_at": "2016-08-09 20:19:36",
      "updated_at": "2016-08-10 17:38:54",
      "updated_by": ""
    }
	

If transfer record isn’t found, Response HTTP Code = 404 and following content is returned:

{"messages":{"error":[{"code":404,"message":"Resource not found."}]}}
	

In case of an XML response:

    <?xml version="1.0"?>
    <magento_api>
      <messages>
        <error>
          <data_item>
            <code>404</code>
            <message>Resource not found.</message>
          </data_item>
        </error>
      </messages>
    </magento_api>
	
PUT /rewards_transfers/:rewards_transfer_id
URL Structure http://{{magentohost}}/api/rest/rewards_transfers/:rewards_transfer_id
Description Allows you to modify an existing rewards_transfer object
Notes Only Admin user can create a new transfer
Authentication Admin
Parameters:

Response

If the transfer was updated successfully, you'll receive HTTP Response Code = 200 with an empty Response Body

rewards_customers

This resource is a full extension of Magento’s standard Customers API Resource with a few differences:

  • Only GET requests are supported.
  • Customer data will contain an extra rewards_active_balance attribute of type int
    • this will be the customer’s usable points balance

End-points include:

GET /rewards_customers
URL Structure http://{{magentohost}}/api/rest/rewards_customers/
Description Allows you to retrieve the list of existing customers along with their usable points balances.
Notes Only Admin user can retrieve the list of customers
Authentication Admin
Optional Parameters:
Note:

If the attribute value consists of several words separated by a whitespace, the %20 sign is used.
For example:
/api/rest/rewards_customers?filter[1][attribute]=name&filter[1][in]=John%20Smith

Response

Response will be an array of zero or more objects of type rewards_customers.
Sample Response:
    [
        {
          "entity_id": "1",
          "website_id": "1",
          "email": "test@mail.com",
          "group_id": "2",
          "created_at": "2013-03-28T22:57:17+00:00",
          "disable_auto_group_change": "0",
          "rewards_active_balance": "5819"
        },
        {
          "entity_id": "2",
          "website_id": "1",
          "email": "test1@mail.com",
          "group_id": "2",
          "created_at": "2014-02-21T22:37:17+00:00",
          "disable_auto_group_change": "0",
          "rewards_active_balance": "5817"
        }
    ]
	
GET /rewards_customers/:customer_id
URL Structure http://{{magentohost}}/api/rest/rewards_customers/{{customer_id}}
Description Allows you to retrieve information on an existing customer.
Notes Only Admin user can retrieve a customer
Authentication Admin
Parameters none
Response

If object is found, a json response will look like this:

    {
          "entity_id": "1",
          "website_id": "1",
          "email": "test@mail.com",
          "group_id": "2",
          "created_at": "2013-03-28T22:57:17+00:00",
          "disable_auto_group_change": "0",
          "rewards_active_balance": "5819"
    }
	

If transfer record isn’t found, Response HTTP Code = 404 and following content is returned:

{"messages":{"error":[{"code":404,"message":"Resource not found."}]}}
	

In case of an XML response:

    <?xml version="1.0"?>
    <magento_api>
      <messages>
        <error>
          <data_item>
            <code>404</code>
            <message>Resource not found.</message>
          </data_item>
        </error>
      </messages>
    </magento_api>
	

Still need help? Get Help Get Help