API documentationgetOrderReturns
The method allows you to download order returns from a specific date from the BaseLinker return manager. The return list can be limited using the filters described in the method parameters. A maximum of 100 order returns are returned at a time.
Input parameters
| order_id | int | Identifier of an order the return was created from. |
| return_id | int | Order return identifier. Completing this field will download information about only one specific order return. |
| date_from | int | The return creation date from which order return are to be collected. Format unix time stamp. |
| id_from | int | The order return ID number from which subsequent order returns are to be collected |
| status_id | int | (optional) The status identifier from which order returns are to be collected. Leave blank to download order returns from all statuses. |
| filter_order_return_source | varchar(20) | (optional) Filtering of order return lists by order return source, for instance "ebay", "amazon" (displays only orders come from given source). The list of order return sources can be retrieved with getOrderSources method. |
| filter_order_return_source_id | int | (optional) Filtering of order return lists by order return source identifier, for instance "2523" (displays only order returns come from order return source defined in "filter_order_return_source" identified by given order return source identifier). Filtering by order return source identifier requires "filter_order_return_source" to be set prior. The list of order source identifiers can be retrieved with getOrderSources method. |
| include_custom_extra_fields | bool | (optional, false by default) Download values of custom additional fields. |
| include_connect_data | bool | (optional, false by default) Base Connect and contractor data. |
Output data
The method returns the data in JSON format.
| status | varchar(30) | SUCCESS - request executed correctly ERROR - an error occurred during an API request. Error details will be described in 2 additional returned fields: error_message and error_code |
| returns | array | An array of information about the order returns found. Each order return is described by the fields listed below. |
| | - return_id | int | Return order identifier. |
| | - order_id | int | Identifier of an order the return was created from. |
| | - shop_order_id | int | Order ID given by the store |
| | - external_order_id | varchar(50) | An order identifier taken from an external source. e.g. the order number in the store, or the eBay transaction number. |
| | - reference_number | varchar(100) | Reference number from external source. |
| | - order_return_source | varchar(20) | Order source - available values: "shop", "personal" or "marketplace_code" e.g. "ebay", "amazon", "ceneo", "emag", "allegro", etc. |
| | - order_return_source_id | int | Source ID (e.g. internal allegro account ID, internal shop ID, etc.). Unique only in combination with the "order_source" field (e.g. an ebay account and an allegro account may have the same ID, but two ebay accounts always have different IDs) |
| | - status_id | int | Order return status (the list available to retrieve with getOrderReturnStatusList). |
| | - date_add | int | Date of order creation (in unix time format). |
| | - date_in_status | int | Date from which the order return is in current status (unix time format). |
| | - user_login | varchar(100) | Marketplace user login |
| | - currency | char(3) | 3-letter currency symbol (e.g. EUR, PLN) |
| | - refunded | char(3) | Information whether the order return is already refunded. |
| varchar(150) | Buyer e-mail address | |
| | - phone | varchar(100) | Buyer phone number |
| | - delivery_price | float | Gross delivery price of a return |
| | - delivery_fullname | varchar(100) | Delivery address - name and surname |
| | - delivery_company | varchar(100) | Delivery address - company |
| | - delivery_address | varchar(100) | Delivery address - street and number |
| | - delivery_postcode | varchar(100) | Delivery address - postcode |
| | - delivery_city | varchar(100) | Delivery address - city |
| | - delivery_state | varchar(20) | Delivery address - state/province |
| | - delivery_country | varchar(50) | Delivery address - country |
| | - delivery_country_code | char(2) | Delivery address - country code (two-letter, e.g. EN) |
| | - extra_field_1 | varchar(50) | Value of the "extra field 1". |
| | - extra_field_2 | varchar(50) | Value of the "extra field 2". |
| | - custom_extra_fields | array | A list containing order custom extra fields returned only if the input parameters include_custom_extra_fields is set to true, where the key is the extra field ID and value is an extra field content for given extra field. The list of extra fields can be retrieved with getOrderReturnExtraFields method. In case of file the following format is returned as value: { "title": "file.pdf" (varchar(40) - the file name) "url": "https://upload.cdn.baselinker.com/order_extra_files/23/..." (url - the file url) } |
| | - admin_comments | varchar(200) | Seller comments |
| | - delivery_package_module | varchar(20) | Courier name (if the shipment was created). |
| | - delivery_package_nr | varchar(40) | Shipping number (if the shipment was created). |
| | - connect_data | array | Data from Base Connect linked to the order. Contains fields described below. connect_integration_id (int) - Base Connect integration ID connect_contractor_id (int) - Base Connect contractor ID connect_sale_id (int) - Order return ID on the Base Connect contractor side |
| | - products | array | An array of order return products. Each element of the array is also an array containing fields described below. storage (text) - type of warehouse from which the product comes (available values: "db" - BaseLinker internal inventory, "shop" - the online store warehouse, "warehouse" - a connected wholesaler). storage_id (int) - the identifier of the warehouse from which the product comes (one of the shops connected to the account). Value "0" for a product from the BaseLinker internal inventory. order_return_product_id (int) - ID of order return item from BaseLinker order manager order_product_id (int) - ID of the original order item from BaseLinker order manager that this return item relates to. Corresponds to order_product_id from getOrders method. Returns 0 if the return item is not linked to a specific order item. product_id (varchar(50)) - Product identifier in BaseLinker or shop storage. Blank if the product number is unknown variant_id (varchar(30)) - Product variant ID. Blank if the variant number is unknown name (varchar(200)) - Product name sku (varchar(50)) - Product sku ean (varchar(32)) - Product ean location (varchar(50)) - Product location warehouse_id (int) - Product source warehouse identifier. Only applies to products from BaseLinker inventory. auction_id (varchar(50)) - Listing ID number (if the order comes from ebay/allegro). attributes (varchar(350)) - Specific product attributes (e.g. "Color: blue") (Variant name) price_brutto (float) - Single item gross price tax_rate (float) - VAT tax rate e.g. "23", (value from range 0-100, EXCEPTION values: "-1" for "EXPT"/"ZW" exempt from VAT, "-0.02" for "NP" annotation, "-0.03" for "OO" VAT reverse charge) quantity (int) - Quantity of pieces weight (float) - Single item weight bundle_id (int) - ID of the bundle that was split to aquire this order item. Only applies to bundles from BaseLinker inventory. Returns 0 if the product was not aquired from splitting a bundle status_id (int) - Identifier of order return item status return_reason_id (int) - Identifier of order return reason return_reason_comment (varchar(500)) - Customer comment about return reason |
| | - order_return_account_number | varchar(50) | Bank account number to issue a refund |
| | - order_return_iban | varchar(34) | IBAN of the bank account |
| | - order_return_swift | varchar(11) | SWIFT of the bank account |
| | - fulfillment_status | int | Fulfillment status ID: 0 - active 5 - accepted 1 - done 2 - canceled |
Sample
Input data:Output data:
A sample request in PHP: