SmartPyme Returns API: List, Retrieve, and Summarize

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}"

import requests

url = "https://api.smartpyme.site/api/external/v1/returns"
headers = {"Authorization": "Bearer {api_key}"}
params = {
    "fecha_inicio": "2025-01-01",
    "fecha_fin": "2025-01-31",
    "per_page": 50,
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const response = await fetch(
  "https://api.smartpyme.site/api/external/v1/returns" +
    "?fecha_inicio=2025-01-01&fecha_fin=2025-01-31&per_page=50",
  {
    method: "GET",
    headers: { Authorization: "Bearer {api_key}" },
  }
);
const data = await response.json();
console.log(data);

Query parameters

string

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.

string

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.

integer

Page number to retrieve. Defaults to 1.

integer

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

boolean

Indicates whether the request completed successfully.

array

Array of return objects matching the applied filters.

Show Return fields

integer

Unique numeric identifier for the return record.

string

Date the return was processed, in Y-m-d format.

string

Human-readable document number assigned to the return (e.g. DEV-001234).

string

Type of return document (e.g. Devolucion).

number

Pre-tax subtotal of all returned line items.

number

Portion of the return amount not subject to tax classification.

number

Tax-exempt portion of the return amount.

number

Amount invoiced on behalf of third parties, when applicable.

number

Final total of the return including tax and after any discounts.

number

Tax amount included in the return total.

number

IVA withheld on the return transaction, when applicable.

string

Free-text notes recorded at the time the return was processed (e.g. reason for return).

integer

Active status of the return record. 1 is active; 0 is voided or inactive.

integer

The ID of the originating sale that this return is associated with. Use this to cross-reference the GET /sales/{id} endpoint.

string

Display name of the customer who made the return.

string

Username of the operator who processed the return.

string

Document type associated with the return (e.g. Nota de Crédito).

string

ISO 8601 timestamp of when the return record was created.

string

ISO 8601 timestamp of the most recent update to the return record.

array

Line items included in this return.

Show Return detail fields

string

Full name of the returned product.

string

Internal SKU or product code of the returned item.

string

Brand name of the returned product.

string

Detailed description of the returned product.

number

Quantity of units returned in this line item. Supports up to three decimal places.

number

Unit price of the product at the time of the original sale.

number

Unit cost of the product, used for margin and inventory value adjustments.

number

Discount amount applied to this returned line item.

number

Portion of this line item’s amount not subject to tax classification.

number

Amount for this line item invoiced on behalf of third parties, when applicable.

number

Tax-exempt portion of this line item’s amount.

number

Line item return total after applying quantity and discount.

string

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

integer

required

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}"

import requests

return_id = 789
url = f"https://api.smartpyme.site/api/external/v1/returns/{return_id}"
headers = {"Authorization": "Bearer {api_key}"}

response = requests.get(url, headers=headers)
print(response.json())

const returnId = 789;
const response = await fetch(
  `https://api.smartpyme.site/api/external/v1/returns/${returnId}`,
  {
    method: "GET",
    headers: { Authorization: "Bearer {api_key}" },
  }
);
const data = await response.json();
console.log(data);

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}"

import requests

url = "https://api.smartpyme.site/api/external/v1/returns/summary"
headers = {"Authorization": "Bearer {api_key}"}
params = {
    "fecha_inicio": "2025-01-01",
    "fecha_fin": "2025-01-31",
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const response = await fetch(
  "https://api.smartpyme.site/api/external/v1/returns/summary" +
    "?fecha_inicio=2025-01-01&fecha_fin=2025-01-31",
  {
    method: "GET",
    headers: { Authorization: "Bearer {api_key}" },
  }
);
const data = await response.json();
console.log(data);

Query parameters

string

Start date for the summary period, in Y-m-d format. Omit to include all return records from the beginning.

string

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

integer

Total number of return transactions processed within the requested period.

number

Gross monetary value of all returns in the period, including tax.

number

Total tax amount included across all return records in the period.

number

Sum of all discounts applied to returned line items in the period.

number

Average value per return transaction, calculated as total_devuelto / cantidad_devoluciones.

array

Breakdown of return count and total value grouped by document type.

Show devoluciones_por_tipo fields

string

The return document type (e.g. Devolucion).

integer

Number of return records with this document type.

number

Combined total value of returns with this document type.

string

Display name of the company associated with your API key.

string

ISO 8601 timestamp indicating when the summary was generated.

object

Echo of the date filters used to compute the summary, useful for confirming the request parameters.

Overview

Endpoints

SmartPyme Returns API: List, Retrieve, and Summarize

GET /returns

Query parameters

Response example

Response fields

GET /returns/{id}

Path parameter

GET /returns/summary

Query parameters

Response example

Response fields

​GET /returns

​Query parameters

​Response example

​Response fields

​GET /returns/{id}

​Path parameter

​GET /returns/summary

​Query parameters

​Response example

​Response fields

GET /returns

Query parameters

Response example

Response fields

GET /returns/{id}

Path parameter

GET /returns/summary

Query parameters

Response example

Response fields