REST API: Resources
Documentation for the deprecated SOAP API feature, can be found here.
Outline
- Overview
- Setup
- Resources
rewards_transfers
GET
/rewards_transfers
POST
/rewards_transfers
GET
/rewards_transfers/:rewards_transfer_id
PUT
/rewards_transfers/:rewards_transfer_id
rewards_customers
- Testing
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
POST
/rewards_transfers
GET
/rewards_transfers/:rewards_transfer_id
PUT
/rewards_transfers/:rewards_transfer_id
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 /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 /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. /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 /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) /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 /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 /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 /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 /api/rest/rewards_transfer?filter[1][attribute]=customer_id&filter[1][from]=1&filter[1][to]=3
|
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
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"5"
(Approved)
|
No | string | "3" |
is_dev_mode |
Indicates if transfer is test/developer mode or not.
false
|
No | boolean | true |
reason_id |
Reason code for the transfer. See list of reasons. "6"
(Administrative Adjustment)
|
No | string | "6" |
effective_start |
Timestamp in UTC to approve this transfer if Pending Time
null
|
No | string | "2012-03-23 14:16:32" |
Response
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
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 typeint
- 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 /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 /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. /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 /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) /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 /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 /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 /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 /api/rest/rewards_customers?filter[1][attribute]=entity_id&filter[1][from]=1&filter[1][to]=3
|
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
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>