| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| v:0.7.0:advanced:api [2011/02/11 08:46] – clarifying how to refeed the sub xml foxybrett | v:0.7.0:advanced:api [2017/04/26 07:02] (current) – external edit 127.0.0.1 |
|---|
| ===== API Actions ===== | ===== API Actions ===== |
| ==== Global Notes, Methods, and Parameters ==== | ==== Global Notes, Methods, and Parameters ==== |
| * All ''_list'' methods support a ''pagination_start'' parameter for paginating through your filtered result set. Along with the ''<messages>'' node with useful pagination information, there will be a ''<statistics>'' node which includes total records, ''filtered_total'', ''pagination_start'', and ''pagination_end''. | * All ''_list'' methods support a ''pagination_start'' parameter for paginating through your filtered result set. Along with the ''<messages>'' node with useful pagination information, there will be a ''<statistics>'' node which includes total records, ''filtered_total'', ''pagination_start'', and ''pagination_end''. 070 shows 50 entries at a time, 071 defaults to 300 but in 071 you can also pass in an ''entries_per_page'' value to override it. |
| * All ''_list'' methods can accept multiple filters. | * All ''_list'' methods can accept multiple filters. |
| * Make sure you've selected the appropriate hashing method (MD5 or SHA-1) in the "advanced" tab in your FoxyCart admin. | * Make sure you've selected the appropriate hashing method in the "advanced" tab in your FoxyCart admin, especially if you're using any ''customer_'' API calls. |
| |
| ==== Customer ==== | ==== Customer ==== |
| === Notes === | === Notes === |
| * The ''customer_password'' value: | * The ''customer_password'' value: |
| * When using ''customer_get'' method: Returns a //HASH// of the customer's password, //NOT THE ACTUAL PASSWORD//. You can set the hashing method in the "Advanced" tab in your FoxyCart admin. As of v0.7.1 this setting is user-specific. | * When using ''customer_get'' method: Returns a //HASH// of the customer's password, //NOT THE ACTUAL PASSWORD//. You can set the hashing method in the "Advanced" tab in your FoxyCart admin. |
| * When using the ''customer_save'' method you can pass the customer's password as cleartext. FoxyCart will create the password hash for you based on your chosen hashing method. <wrap tip>**v0.7.0: Sending the cleartext is strongly recommended**</wrap> if you have access to it when you make the API request, as this will give FoxyCart additional flexibility with internal hashing methods and password reset functionality. In v0.7.1+ the password hashing and password reset functionality has been improved, and it doesn't matter if you pass in cleartext or a hash. | * When using the ''customer_save'' method you can pass the customer's password as cleartext. FoxyCart will create the password hash for you based on your chosen hashing method. |
| * The ''customer_password_hash'' value: If you do not have the password in cleartext but would like to update the password, pass in ''customer_password_hash''. Whether you pass in a ''customer_password'' or a ''customer_password_hash'', the end result is the same: A hashed password will be returned on ''_get'' requests for the ''customer_password'' field. | * The ''customer_password_hash'' value: If you do not have the password in cleartext but would like to update the password, pass in ''customer_password_hash''. Whether you pass in a ''customer_password'' or a ''customer_password_hash'', the end result is the same: A hashed password will be returned on ''_get'' requests for the ''customer_password'' field. |
| * The ''cc_number'' field will return a //masked// card number if a payment method is saved. Otherwise it will be empty. | * The ''cc_number'' field will return a //masked// card number if a payment method is saved. Otherwise it will be empty. |
| : **Filter Options:** | : **Filter Options:** |
| * ''transaction_date_filter_begin'' (YYYY-MM-DD), ''transaction_date_filter_end'' (YYYY-MM-DD) | * ''transaction_date_filter_begin'' (YYYY-MM-DD), ''transaction_date_filter_end'' (YYYY-MM-DD) |
| * ''is_test_filter'', ''hide_transaction_filter'', ''data_is_fed_filter'', ''id_filter'', ''order_total_filter'', ''coupon_code_filter'' | * ''is_test_filter'', ''hide_transaction_filter'', ''data_is_fed_filter'' (0 or 1), ''id_filter'', ''order_total_filter'', ''coupon_code_filter'' |
| * ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'', ''customer_state_filter'', ''shipping_state_filter'', ''customer_ip_filter'' | * ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'', ''customer_state_filter'', ''shipping_state_filter'', ''customer_ip_filter'' |
| * ''product_code_filter'', ''product_name_filter'', ''product_option_name_filter'', ''product_option_value_filter'' | * ''product_code_filter'', ''product_name_filter'', ''product_option_name_filter'', ''product_option_value_filter'' |
| : **Required Fields:** ''transaction_id'' | : **Required Fields:** ''transaction_id'' |
| : **Accepts:** ''data_is_fed'' (0 or 1) | : **Accepts:** ''data_is_fed'' (0 or 1) |
| | : **Notes:** Changing this bit has no impact on anything other than the value of this bit. (ie. It does not tell FoxyCart to refeed the datafeed to your endpoint) |
| |
| ==== Subscriptions ==== | ==== Subscriptions ==== |
| | |
| ; ''subscription_get'' | ; ''subscription_get'' |
| : **Required Fields:** ''sub_token'' (either the token by itself or the complete ''sub_token'' URL) | : **Required Fields:** ''sub_token'' (either the token by itself or the complete ''sub_token'' URL) |
| * ''is_active_filter'' | * ''is_active_filter'' |
| * ''frequency_filter'' | * ''frequency_filter'' |
| * ''past_due_amount_filter'' (set as ''1'' to return subscriptions with past due amounts greater than 0) | * ''past_due_amount_filter'' (if you include this filter and give it a value (such as ''1'') it will return subscriptions with past due amounts greater than 0) |
| * ''start_date_filter_begin'', ''start_date_filter_end'', ''next_transaction_date_filter_begin'', ''next_transaction_date_filter_end'', ''end_date_filter_begin'', ''end_date_filter_end'' (YYYY-MM-DD) | * ''start_date_filter_begin'', ''start_date_filter_end'', ''next_transaction_date_filter_begin'', ''next_transaction_date_filter_end'', ''end_date_filter_begin'', ''end_date_filter_end'' (YYYY-MM-DD) |
| * ''third_party_id_filter'' (for PayPal Standard recurring payments) | * ''third_party_id_filter'' (for PayPal Express Checkout recurring payments) |
| * ''last_transaction_id_filter'' | * ''last_transaction_id_filter'' |
| * ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'' | * ''customer_id_filter'', ''customer_email_filter'', ''customer_first_name_filter'', ''customer_last_name_filter'' |
| You can always use [[http://curl.haxx.se/docs/httpscripting.html|CURL]] to test the API. Here is an example command line CURL request: | You can always use [[http://curl.haxx.se/docs/httpscripting.html|CURL]] to test the API. Here is an example command line CURL request: |
| <code> | <code> |
| curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=customer_get&customer_email=john.doe@example.com" https://example.foxycart.tld/api | curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=customer_get&customer_email=john.doe@example.com" https://example.foxycart.com/api |
| </code> | </code> |
| You'd obviously need to insert your own values in that call, but it's provided here for reference. Using CURL can be handy if you just want to get a customer ID quickly, or test to ensure data is being returned as expected. | You'd obviously need to insert your own values in that call, but it's provided here for reference. Using CURL can be handy if you just want to get a customer ID quickly, or test to ensure data is being returned as expected. |
| Here's an example to retrieve a transaction: | Here's an example to retrieve a transaction: |
| <code> | <code> |
| curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=transaction_get&transaction_id=1234567890" https://example.foxycart.tld/api | curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=transaction_get&transaction_id=1234567890" https://example.foxycart.com/api |
| | </code> |
| | And here's how to refeed the [[:static:redirect:subscription_datafeed|subscription XML datafeed]]: |
| | <code> |
| | curl -d "api_token=PUT_YOUR_API_KEY_HERE&api_action=subscription_datafeed" https://example.foxycart.com/api |
| </code> | </code> |
