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:
Name Description
page Specifies the page number which items will be returned
Example: /api/rest/rewards_transfer?page=1
order, dir Specifies the sort order of returned items and the order direction: 'asc' - returns items in the ascending order; 'dsc' - returns items in the descending order
Example: • /api/rest/rewards_transfer?order=quantity&dir=dsc
• /api/rest/rewards_transfer?order=quantity&dir=asc
limit Limits the number of returned items in the response.
Note that by default, 10 items are returned in the response. The maximum number is 100 items.
Example: /api/rest/rewards_transfer?limit=2
filter Specifies the filters for returned data.
Used in combination with parameters below.
neq "not equal to" - returns items with the specified attribute that is not equal to the defined value
Example: /api/rest/rewards_transfer?filter[1][attribute]=customer_id&filter[1][neq]=6
in "equals any of" - returns items that are equal to the item(s) with the specified attribute(s)
Example: /api/rest/rewards_transfer?filter[1][attribute]=customer_id&filter[1][in]=3
nin "not equals any of" - returns items excluding the item with the specified attribute
Example: /api/rest/rewards_transfer?filter[1][attribute]=customer_id&filter[1][nin]=3
gt "greater than" - returns items with the specified attribute that is greater than the defined value
Example: /api/rest/rewards_transfer?filter[1][attribute]=quantity&filter[1][gt]=500
lt "less than" - returns items with the specified attribute that is less than the defined value
Example: /api/rest/rewards_transfer?filter[1][attribute]=quantity&filter[1][lt]=500
from, to Specifies the range of attributes according to which items will be returned
Example: /api/rest/rewards_transfer?filter[1][attribute]=customer_id&filter[1][from]=1&filter[1][to]=3
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:
Name Description Required Type Example Value
customer_id Magento Customer ID of person to issue transfer to Yes string "3"
quantity Number of Points in the transfer Yes int 500
comments Comments for the transfer No string "Issuing points for administrative reason"
status_id Status code representing state of transfer.
One of:
• "5": Approved
• "3": Pending Approval
• "4": Pending Event
• "6": Pending Time
Default: "5" (Approved)
No string "3"
is_dev_mode Indicates if transfer is test/developer mode or not.
Default: false
No boolean true
reason_id Reason code for the transfer.
See list of reasons.
Default: "6" (Administrative Adjustment)
No string "6"
effective_start Timestamp in UTC to approve this transfer if Pending Time
Default: null
No string "2012-03-23 14:16:32"

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:
Name Description Required Type Example Value
quantity Number of Points in the transfer Yes int 500
comments Comments for the transfer No string "Issuing points for administrative reason"
status_id Status code representing state of transfer.
One of:
• "5": Approved
• "3": Pending Approval
• "4": Pending Event
• "6": Pending Time
 No string "3"
is_dev_mode Indicates if transfer is test/developer mode or not. No boolean true
reason_id Reason code for the transfer.
See list of reasons. 		No string "6"
effective_start Timestamp in UTC to approve this transfer if Pending Time No string "2012-03-23 14:16:32"

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:
Name Description
page Specifies the page number which items will be returned
Example: /api/rest/rewards_customers?page=1
order, dir Specifies the sort order of returned items and the order direction: 'asc' - returns items in the ascending order; 'dsc' - returns items in the descending order
Example: • /api/rest/rewards_customers?order=entity_id&dir=dsc
• /api/rest/rewards_customers?order=entity_id&dir=asc
limit Limits the number of returned items in the response.
Note that by default, 10 items are returned in the response. The maximum number is 100 items.
Example: /api/rest/rewards_customers?limit=2
filter Specifies the filters for returned data.
Used in combination with parameters below.
neq "not equal to" - returns items with the specified attribute that is not equal to the defined value
Example: /api/rest/rewards_customers?filter[1][attribute]=entity_id&filter[1][neq]=6
in "equals any of" - returns items that are equal to the item(s) with the specified attribute(s)
Example: /api/rest/rewards_customers?filter[1][attribute]=entity_id&filter[1][in]=3
nin "not equals any of" - returns items excluding the item with the specified attribute
Example: /api/rest/rewards_customers?filter[1][attribute]=entity_id&filter[1][nin]=3
gt "greater than" - returns items with the specified attribute that is greater than the defined value
Example: /api/rest/rewards_customers?filter[1][attribute]=entity_id&filter[1][gt]=23
lt "less than" - returns items with the specified attribute that is less than the defined value
Example: /api/rest/rewards_customers?filter[1][attribute]=entity_id&filter[1][lt]=33
from, to Specifies the range of attributes according to which items will be returned
Example: /api/rest/rewards_customers?filter[1][attribute]=entity_id&filter[1][from]=1&filter[1][to]=3
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