Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API documentation for refund creation is incorrect #28

Open
villesiltala opened this issue May 6, 2019 · 2 comments
Labels

Comments

@villesiltala
Copy link

@villesiltala villesiltala commented May 6, 2019

The API documentation for orders describes the data format for API requests for orders. Creating a refund via the REST API does not seem to follow this format. Looking at the core code in wc_create_refund() function reveals that the handling for line items does not match the data format described in the documentation.

To Reproduce
Steps to reproduce the behavior:

  1. Create a test order with items to refund.
  2. Create a JSON following the API documentation:
{
    "line_items": [
        {
            "id": 1234, // id matching a line item
            "quantity": 1,
            "product_id": 5678, // id matching the line item product
            "variant_id": 9012, // id matching the line item product variant
        }
    ],
    "api_refund": false,
    "reason": "Testing the refund data format"
}
  1. Post this JSON to the REST API
  2. See the following data without the correct line item data:
{
  "id": 372,
  "date_created": "2019-05-06T11:25:12",
  "date_created_gmt": "2019-05-06T08:25:12",
  "amount": "0.00",
  "reason": "Testing the refund data format",
  "refunded_by": 1,
  "meta_data": [],
  "line_items": [],
  "_links": {
    "self": [
      {
        "href": "https:\/\/my-site.test\/wp-json\/wc\/v3\/orders\/361\/refunds\/372"
      }
    ],
    "collection": [
      {
        "href": "https:\/\/my-site.test\/wp-json\/wc\/v3\/orders\/361\/refunds"
      }
    ],
    "up": [
      {
        "href": "https:\/\/my-site.test\/wp-json\/wc\/v3\/orders\/361"
      }
    ]
  }
}

Expected behavior
The refund should be created for the defined line item and stocks should be recalculated based on the refunded quantity. Order total should be recalculated after the refunds.

First of all, the documentation describes the line item id as a read-only property. Thus, my example data is invalid, but I don't see any other way to match the line item other than setting the id. Looking at the code and going through issues about the refund endpoint online, I found out that the line item id should be set as an object key for the line items object. This means the line_items property should not be an array after all. This is not documented correctly. Here's a working example of how to format the object:

	"line_items": {
		"123": {}
	},

Here "123" is the line item id. I would prefer my example formatting as it is more consistent with the GET endpoint and the current documentation.

Then, the quantity property is not working. Again, looking at the code reveals the wc_create_function() function handles the quantity by a qty property. This is documented incorrectly.

Another incorrectly documented property for line items is the total property. wc_create_refund() expects it to come from a property called refund_total. This is not documented in the order line items section.

The amount handling should also be described more thoroughly. Now the order total is not refunded without a top-level property of amount defining the amount to be reduced from the order total. If a request with only the line item refund is made, the line item is refunded and stocks are recalculated but the order total does not change. Here's an example of a partially working line item refund request data:

{
	"line_items": {
		"841": {
			"qty": 1,
			"product_id": 200,
			"variation_id": 206,
			"refund_total": "7.90"
		}
	},
	"api_refund": false,
	"reason": "Testing"
}

And here's the fully working request:

{
	"amount": "7.90",
	"line_items": {
		"841": {
			"qty": 1,
			"product_id": 200,
			"variation_id": 206,
			"refund_total": "7.90"
		}
	},
	"api_refund": false,
	"reason": "Testing"
}

As you can see the documentation for creating a refund has many errors and inconsistencies. Please fix them and provide a simple and clean way of creating refunds through the REST API.

``` ### WordPress Environment ###

Home URL: https://checkout.test
Site URL: https://checkout.test
WC Version: 3.5.7
Log Directory Writable: ✔
WP Version: 5.1.1
WP Multisite: –
WP Memory Limit: 256 MB
WP Debug Mode: ✔
WP Cron: ✔
Language: fi
External object cache: ✔

Server Environment

Server Info: nginx/1.11.2
PHP Version: 7.1.26-1+ubuntu16.04.1+deb.sury.org+1 - We recommend using PHP version 7.2 or above for greater performance and security. How to update your PHP version
PHP Post Max Size: 10 MB
PHP Time Limit: 600
PHP Max Input Vars: 1000
cURL Version: 7.47.0
OpenSSL/1.0.2g

SUHOSIN Installed: –
MySQL Version: 5.5.5-10.3.7-MariaDB-1:10.3.7+maria~jessie
Max Upload Size: 10 MB
Default Timezone is UTC: ✔
fsockopen/cURL: ✔
SoapClient: ✔
DOMDocument: ✔
GZip: ✔
Multibyte String: ✔
Remote Post: ✔
Remote Get: ✔

Database

WC Database Version: 3.5.7
WC Database Prefix: wp_
MaxMind GeoIP Database: ✔
Total Database Size: 2.72MB
Database Data Size: 1.36MB
Database Index Size: 1.36MB
wp_woocommerce_sessions: Data: 0.08MB + Index: 0.02MB
wp_woocommerce_api_keys: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_attribute_taxonomies: Data: 0.02MB + Index: 0.02MB
wp_woocommerce_downloadable_product_permissions: Data: 0.02MB + Index: 0.05MB
wp_woocommerce_order_items: Data: 0.05MB + Index: 0.02MB
wp_woocommerce_order_itemmeta: Data: 0.17MB + Index: 0.19MB
wp_woocommerce_tax_rates: Data: 0.02MB + Index: 0.06MB
wp_woocommerce_tax_rate_locations: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_shipping_zones: Data: 0.02MB + Index: 0.00MB
wp_woocommerce_shipping_zone_locations: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_shipping_zone_methods: Data: 0.02MB + Index: 0.00MB
wp_woocommerce_payment_tokens: Data: 0.02MB + Index: 0.02MB
wp_woocommerce_payment_tokenmeta: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_log: Data: 0.02MB + Index: 0.02MB
wp_commentmeta: Data: 0.02MB + Index: 0.03MB
wp_comments: Data: 0.11MB + Index: 0.09MB
wp_links: Data: 0.02MB + Index: 0.02MB
wp_options: Data: 0.11MB + Index: 0.02MB
wp_postmeta: Data: 0.34MB + Index: 0.38MB
wp_posts: Data: 0.08MB + Index: 0.06MB
wp_termmeta: Data: 0.02MB + Index: 0.03MB
wp_terms: Data: 0.02MB + Index: 0.03MB
wp_term_relationships: Data: 0.02MB + Index: 0.02MB
wp_term_taxonomy: Data: 0.02MB + Index: 0.03MB
wp_usermeta: Data: 0.02MB + Index: 0.03MB
wp_users: Data: 0.02MB + Index: 0.05MB
wp_wc_download_log: Data: 0.02MB + Index: 0.03MB
wp_wc_webhooks: Data: 0.02MB + Index: 0.02MB

Post Type Counts

attachment: 5
json_consumer: 9
page: 5
post: 1
product: 6
product_variation: 6
revision: 1
scheduled-action: 52
shop_order: 59
shop_order_refund: 48

Security

Secure connection (HTTPS): ✔
Hide errors from visitors: Error messages should not be shown to visitors.

Active Plugins (4)

WP REST API - OAuth 1.0a Server: by WP REST API Team – 0.3.0
WooCommerce: by Automattic – 3.5.7 – 3.6.2 is available

Settings

API Enabled: –
Force SSL: –
Currency: EUR (€)
Currency Position: right_space
Thousand Separator:
Decimal Separator: ,
Number of Decimals: 2
Taxonomies: Product Types: external (external)
grouped (grouped)
simple (simple)
variable (variable)

Taxonomies: Product Visibility: exclude-from-catalog (exclude-from-catalog)
exclude-from-search (exclude-from-search)
featured (featured)
outofstock (outofstock)
rated-1 (rated-1)
rated-2 (rated-2)
rated-3 (rated-3)
rated-4 (rated-4)
rated-5 (rated-5)

WC Pages

Shop base: woocommerce/woocommerce#3 - /shop/
Cart: woocommerce/woocommerce#4 - /cart/
Checkout: woocommerce/woocommerce#5 - /checkout/
My account: woocommerce/woocommerce#6 - /my-account/
Terms and conditions: Page not set

Theme

Name: Storefront
Version: 2.4.1 – 2.4.6 is available
Author URL: https://woocommerce.com/
Child Theme: – If you are modifying WooCommerce on a parent theme that you did not build personally we recommend using a child theme. See: How to create a child theme
WooCommerce Support: ✔

Templates

Overrides: –
`

Isolating the problem (mark completed items with an [x]):

  • I have deactivated other plugins and confirmed this bug occurs when only WooCommerce plugin is active.
  • This bug happens with a default WordPress theme active, or Storefront.
  • I can reproduce this bug consistently using the steps above.

WordPress Environment

``` ### WordPress Environment ###

Home URL: https://checkout.test
Site URL: https://checkout.test
WC Version: 3.5.7
Log Directory Writable: ✔
WP Version: 5.1.1
WP Multisite: –
WP Memory Limit: 256 MB
WP Debug Mode: ✔
WP Cron: ✔
Language: fi
External object cache: ✔

Server Environment

Server Info: nginx/1.11.2
PHP Version: 7.1.26-1+ubuntu16.04.1+deb.sury.org+1 - We recommend using PHP version 7.2 or above for greater performance and security. How to update your PHP version
PHP Post Max Size: 10 MB
PHP Time Limit: 600
PHP Max Input Vars: 1000
cURL Version: 7.47.0
OpenSSL/1.0.2g

SUHOSIN Installed: –
MySQL Version: 5.5.5-10.3.7-MariaDB-1:10.3.7+maria~jessie
Max Upload Size: 10 MB
Default Timezone is UTC: ✔
fsockopen/cURL: ✔
SoapClient: ✔
DOMDocument: ✔
GZip: ✔
Multibyte String: ✔
Remote Post: ✔
Remote Get: ✔

Database

WC Database Version: 3.5.7
WC Database Prefix: wp_
MaxMind GeoIP Database: ✔
Total Database Size: 2.72MB
Database Data Size: 1.36MB
Database Index Size: 1.36MB
wp_woocommerce_sessions: Data: 0.08MB + Index: 0.02MB
wp_woocommerce_api_keys: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_attribute_taxonomies: Data: 0.02MB + Index: 0.02MB
wp_woocommerce_downloadable_product_permissions: Data: 0.02MB + Index: 0.05MB
wp_woocommerce_order_items: Data: 0.05MB + Index: 0.02MB
wp_woocommerce_order_itemmeta: Data: 0.17MB + Index: 0.19MB
wp_woocommerce_tax_rates: Data: 0.02MB + Index: 0.06MB
wp_woocommerce_tax_rate_locations: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_shipping_zones: Data: 0.02MB + Index: 0.00MB
wp_woocommerce_shipping_zone_locations: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_shipping_zone_methods: Data: 0.02MB + Index: 0.00MB
wp_woocommerce_payment_tokens: Data: 0.02MB + Index: 0.02MB
wp_woocommerce_payment_tokenmeta: Data: 0.02MB + Index: 0.03MB
wp_woocommerce_log: Data: 0.02MB + Index: 0.02MB
wp_commentmeta: Data: 0.02MB + Index: 0.03MB
wp_comments: Data: 0.11MB + Index: 0.09MB
wp_links: Data: 0.02MB + Index: 0.02MB
wp_options: Data: 0.11MB + Index: 0.02MB
wp_postmeta: Data: 0.34MB + Index: 0.38MB
wp_posts: Data: 0.08MB + Index: 0.06MB
wp_termmeta: Data: 0.02MB + Index: 0.03MB
wp_terms: Data: 0.02MB + Index: 0.03MB
wp_term_relationships: Data: 0.02MB + Index: 0.02MB
wp_term_taxonomy: Data: 0.02MB + Index: 0.03MB
wp_usermeta: Data: 0.02MB + Index: 0.03MB
wp_users: Data: 0.02MB + Index: 0.05MB
wp_wc_download_log: Data: 0.02MB + Index: 0.03MB
wp_wc_webhooks: Data: 0.02MB + Index: 0.02MB

Post Type Counts

attachment: 5
json_consumer: 9
page: 5
post: 1
product: 6
product_variation: 6
revision: 1
scheduled-action: 52
shop_order: 59
shop_order_refund: 48

Security

Secure connection (HTTPS): ✔
Hide errors from visitors: Error messages should not be shown to visitors.

Active Plugins (4)

WP REST API - OAuth 1.0a Server: by WP REST API Team – 0.3.0
WooCommerce: by Automattic – 3.5.7 – 3.6.2 is available

Settings

API Enabled: –
Force SSL: –
Currency: EUR (€)
Currency Position: right_space
Thousand Separator:
Decimal Separator: ,
Number of Decimals: 2
Taxonomies: Product Types: external (external)
grouped (grouped)
simple (simple)
variable (variable)

Taxonomies: Product Visibility: exclude-from-catalog (exclude-from-catalog)
exclude-from-search (exclude-from-search)
featured (featured)
outofstock (outofstock)
rated-1 (rated-1)
rated-2 (rated-2)
rated-3 (rated-3)
rated-4 (rated-4)
rated-5 (rated-5)

WC Pages

Shop base: woocommerce/woocommerce#3 - /shop/
Cart: woocommerce/woocommerce#4 - /cart/
Checkout: woocommerce/woocommerce#5 - /checkout/
My account: woocommerce/woocommerce#6 - /my-account/
Terms and conditions: Page not set

Theme

Name: Storefront
Version: 2.4.1 – 2.4.6 is available
Author URL: https://woocommerce.com/
Child Theme: – If you are modifying WooCommerce on a parent theme that you did not build personally we recommend using a child theme. See: How to create a child theme
WooCommerce Support: ✔

Templates

Overrides: –

</details>
@vedanshujain

This comment has been minimized.

Copy link

@vedanshujain vedanshujain commented Aug 21, 2019

Right now we only officially support the amount field to be used by external clients when creating refunds.

That said we should support and document better refund API, I am marking this issue as an enhancement.

@claudiosanches claudiosanches transferred this issue from woocommerce/woocommerce Aug 29, 2019
@issue-label-bot issue-label-bot bot added the type: bug label Aug 29, 2019
@issue-label-bot

This comment has been minimized.

Copy link

@issue-label-bot issue-label-bot bot commented Aug 29, 2019

Issue-Label Bot is automatically applying the label type: bug to this issue, with a confidence of 0.93. Please mark this comment with 👍 or 👎 to give our bot feedback!

Links: app homepage, dashboard and code for this bot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.