The Returns endpoints expose all sales return transactions recorded in SmartPyme, allowing you to reconcile inventory adjustments, audit customer refund activity, and track returned merchandise at the line-item level. Each return record links back to its originating sale via id_venta and includes a full detalles breakdown of returned products. All requests must include your API key in the Authorization header.
GET /returns Returns a paginated list of sales return records. Filter by date range to scope the results to a specific period. Each record includes header-level return information and a detalles array of the individual products that were returned.
curl --request GET \ --url "https://api.smartpyme.site/api/external/v1/returns?fecha_inicio=2025-01-01&fecha_fin=2025-01-31&per_page=50" \ --header "Authorization: Bearer {api_key}"
Query parameters Start date for filtering returns, in Y-m-d format (e.g. 2025-01-01). Use together with fecha_fin to define a date range.
End date for filtering returns, in Y-m-d format (e.g. 2025-01-31). Use together with fecha_inicio to define a date range.
Page number to retrieve. Defaults to 1.
Number of records per page. Accepts values between 1 and 200. Defaults to 100.
Response example { "success" : true , "data" : [ { "id" : 789 , "fecha" : "2025-01-20" , "correlativo" : "DEV-001234" , "tipo" : "Devolucion" , "sub_total" : 130.00 , "no_sujeta" : 0.00 , "exenta" : 0.00 , "cuenta_a_terceros" : 0.00 , "total" : 149.50 , "iva" : 19.50 , "iva_retenido" : 0.00 , "observaciones" : "Producto defectuoso" , "enable" : 1 , "id_venta" : 12345 , "nombre_cliente" : "Juan Pérez" , "nombre_usuario" : "admin" , "nombre_documento" : "Nota de Crédito" , "created_at" : "2025-01-20T14:00:00Z" , "updated_at" : "2025-01-20T14:00:00Z" , "detalles" : [ { "nombre_producto" : "Laptop Dell Inspiron" , "codigo_producto" : "LAP-DELL-001" , "marca_producto" : "Dell" , "descripcion" : "Laptop Dell Inspiron 15" , "cantidad" : 1 , "precio" : 130.00 , "costo" : 100.00 , "descuento" : 0.00 , "no_sujeta" : 0.00 , "cuenta_a_terceros" : 0.00 , "exenta" : 0.00 , "total" : 149.50 , "medida" : "Unidad" } ] } ], "pagination" : { "current_page" : 1 , "per_page" : 50 , "total" : 45 , "total_pages" : 1 , "has_next" : false , "has_prev" : false }, "meta" : { "empresa" : "Mi Empresa S.A." , "timestamp" : "2025-01-31T15:00:00Z" , "filters_applied" : { "fecha_inicio" : "2025-01-01" , "fecha_fin" : "2025-01-31" } } }
Response fields Indicates whether the request completed successfully.
Array of return objects matching the applied filters. Unique numeric identifier for the return record.
Date the return was processed, in Y-m-d format.
Human-readable document number assigned to the return (e.g. DEV-001234).
Type of return document (e.g. Devolucion).
Pre-tax subtotal of all returned line items.
Portion of the return amount not subject to tax classification.
Tax-exempt portion of the return amount.
Amount invoiced on behalf of third parties, when applicable.
Final total of the return including tax and after any discounts.
Tax amount included in the return total.
IVA withheld on the return transaction, when applicable.
Free-text notes recorded at the time the return was processed (e.g. reason for return).
Active status of the return record. 1 is active; 0 is voided or inactive.
The ID of the originating sale that this return is associated with. Use this to cross-reference the GET /sales/{id} endpoint. Display name of the customer who made the return.
Username of the operator who processed the return.
Document type associated with the return (e.g. Nota de Crédito).
ISO 8601 timestamp of when the return record was created.
ISO 8601 timestamp of the most recent update to the return record.
Line items included in this return. Show Return detail fields
Full name of the returned product.
Internal SKU or product code of the returned item.
Brand name of the returned product.
Detailed description of the returned product.
Quantity of units returned in this line item. Supports up to three decimal places.
Unit price of the product at the time of the original sale.
Unit cost of the product, used for margin and inventory value adjustments.
Discount amount applied to this returned line item.
Portion of this line item’s amount not subject to tax classification.
Amount for this line item invoiced on behalf of third parties, when applicable.
Tax-exempt portion of this line item’s amount.
Line item return total after applying quantity and discount.
Unit of measure for the returned product (e.g. Unidad, Kg, Litro).
GET /returns/{id} Retrieves a single return record by its numeric ID. The response returns the same full Return object described above, including the detalles array of returned line items.
Path parameter The unique numeric identifier of the return record you want to retrieve.
curl --request GET \ --url "https://api.smartpyme.site/api/external/v1/returns/789" \ --header "Authorization: Bearer {api_key}"
The response wraps the Return object under a data key with "success": true. All fields, including detalles, are identical to the structure documented in the GET /returns response above.
GET /returns/summary Returns aggregate statistics for your return activity over an optional date range. Use this endpoint to measure the volume and value of merchandise being returned, identify high-return periods, and quantify the financial impact of returns on your revenue.
curl --request GET \ --url "https://api.smartpyme.site/api/external/v1/returns/summary?fecha_inicio=2025-01-01&fecha_fin=2025-01-31" \ --header "Authorization: Bearer {api_key}"
Query parameters Start date for the summary period, in Y-m-d format. Omit to include all return records from the beginning.
End date for the summary period, in Y-m-d format. Omit to include all records up to the current date.
Response example { "success" : true , "data" : { "cantidad_devoluciones" : 45 , "total_devuelto" : 6750.00 , "total_iva" : 607.50 , "total_descuentos" : 125.00 , "promedio_devolucion" : 150.00 , "devoluciones_por_tipo" : [ { "tipo" : "Devolucion" , "cantidad" : 45 , "total" : 6750.00 } ] }, "meta" : { "empresa" : "Mi Empresa S.A." , "timestamp" : "2025-01-31T23:59:00Z" , "filters_applied" : { "fecha_inicio" : "2025-01-01" , "fecha_fin" : "2025-01-31" } } }
Response fields data.cantidad_devoluciones
Total number of return transactions processed within the requested period.
Gross monetary value of all returns in the period, including tax.
Total tax amount included across all return records in the period.
Sum of all discounts applied to returned line items in the period.
Average value per return transaction, calculated as total_devuelto / cantidad_devoluciones.
data.devoluciones_por_tipo
Breakdown of return count and total value grouped by document type. Show devoluciones_por_tipo fields
The return document type (e.g. Devolucion).
Number of return records with this document type.
Combined total value of returns with this document type.
Display name of the company associated with your API key.
ISO 8601 timestamp indicating when the summary was generated.
Echo of the date filters used to compute the summary, useful for confirming the request parameters.
