Edara API v3

Edara API v3: Sales Returns

Read the guide first: authentication, paging, errors, rate limits and the shared PagedResult, BatchResult and *Reference shapes.

Endpoints

GET /v3/sales-returns: Gets a sales return by code.

Operation GetSalesReturnByCode · permission read:sales-return

Query string

field type required description
code string yes The sales return code.

Responses: OK SalesReturnResponse: The sales return.

Notes


GET /v3/sales-returns/returnable: Gets the return proposal for an order.

Operation GetReturnableSalesReturn · permission read:sales-return

Query string

field type required description
code string yes Required. Sales-order code, issue-offering code, or a reference number that resolves to one.

Responses: OK ReturnableSalesReturnResponse: The return proposal.

Business errors (HTTP 409, match on errorCode):

Notes


POST /v3/sales-returns: Creates a sales return by referencing an existing sales order or issue offering, with line details resolved from that document.

Operation CreateSalesReturn · permission create:sales-return

Body: CreateSalesReturnRequest

field type default validation description
warehouseId int? NotNull() .GreaterThan(0) Receiving warehouse id. Required.
sourceDocumentCode string NotEmpty() .Must(code => code != null && (code.IndexOf("SO-", StringComparison.OrdinalIgnoreCase) >= 0 || code.IndexOf("IO-", StringComparison.OrdinalIgnoreCase) >= 0)) A Sales Order code ("SO-...") or Issue Offering code ("IO-..."). Required.
documentDate DateTime? NotNull() Document date (ISO 8601). Required.
notes string Free-text notes.
cashAmount decimal? Cash amount returned to the customer.
cashAccountId int? Cash/bank account id. Required only when the calling user's permissions require an automatic cash-out and CashAmount is greater than zero.
exchangeRate decimal? GreaterThan(0) .When(x => x.ExchangeRate.HasValue) Exchange rate to system currency. Omitted means the referenced document's own exchange rate.
returnDiscount decimal? GreaterThanOrEqualTo(0) .When(x => x.ReturnDiscount.HasValue) Order-level discount amount.
sourceDocumentDetails List<CreateSalesReturnDetailRequest> each: NotNull() .SetValidator(new CreateSalesReturnDetailRequestValidator()) .When(x => x.SourceDocumentDetails != null) Lines to return. Omitted entirely means every returnable item on the referenced document.

Responses: Created SalesReturnResponse: Sales return created.

Business errors (HTTP 409, match on errorCode):

Notes

Types

AccountReference

Lightweight account reference (id + code + name).

field type description
id int The account id.
code string The account code.
name string The account name.

CreateSalesReturnDetailRequest

One line of a sales return, identified by the exact line it returns against on the referenced sales order or issue offering.

field type validation description
sourceSalesOrderDetailId int? Detail id on the referenced sales order. At least one of this or SourceWorkOrderDetailId is required; supplying both is validated against the resolved line. Alone, it must resolve to a service item.
sourceWorkOrderDetailId int? Detail id on the referenced issue offering. At least one of this or SourceSalesOrderDetailId is required; supplying both is validated against the resolved line.
quantity decimal? GreaterThan(0) .When(x => x.Quantity.HasValue) Quantity to return. Omitted means the line's full remaining returnable quantity.
price decimal? GreaterThanOrEqualTo(0) .When(x => x.Price.HasValue) Line price. Omitted means the referenced document's own price for this line.

CurrencyReference

Lightweight currency reference (id + ISO code + name).

field type description
id int The currency id.
code string The ISO 4217 currency code.
name string The currency name.

CustomerReference

Lightweight customer reference (id + code + name).

field type description
id int The customer id.
code string The customer code.
name string The customer name.

DocumentType

Document type codes shared across sales, purchase, and warehouse domains.

Values (sent/returned as the name): RS, RR, RT, IO, IR, IT, TR, CI, CO, JE, SI, PI, CN, DN, NR, NP, SO, SR, RecSO, PO, PR, OB, RMA

ReturnableSalesReturnLineResponse

A single returnable line within a ReturnableSalesReturnResponse.

field type description
sourceSalesOrderDetailId int? Detail id on the originating sales order, when one exists.
sourceWorkOrderDetailId int? Detail id on the originating work order (IO), when one exists.
relatedWorkOrderCode string The IO this line was actually delivered on and must be submitted with this line when creating a return. A single order can be fulfilled by more than one IO - null for pure service lines, which have none.
stockItem StockItemReference The returned stock item. Null for service lines.
serviceItem ServiceItemReference The returned service item. Null for goods lines.
quantity decimal Quantity still returnable (delivered minus already returned).
unitOfMeasure UnitOfMeasureReference Unit of measure the returnable quantity is expressed in.
unitPrice decimal Unit price before discount/tax, as originally sold.
price decimal Unit price actually used for Total - tax-exclusive, in settlement currency.
taxRate decimal Tax rate from the original sale.
unitDiscount decimal Discount per unit.
total decimal Quantity × Price.
discount decimal Quantity × UnitDiscount.
lineTax decimal Tax amount for this line.
batchNumber string Batch number, when batch tracking is in use.
expiryDate DateTime? Batch expiry date.

ReturnableSalesReturnResponse

The computed return proposal for an order: everything a caller needs to build a POST /v3/sales-returns request for a full or partial return.

field type description
customer CustomerReference Customer on the original order, locked for the return.
salesPerson SalesPersonReference Salesperson on the original order, when one is set.
currency CurrencyReference Currency the original order was placed in. The system currency when the order didn't set one explicitly.
exchangeRate decimal Exchange rate to system currency. Needed to submit POST /v3/sales-returns for a non-system-currency order.
grossTotal decimal Gross total, before discounts and taxes.
subTotal decimal Sub-total after item discounts, before taxes.
netTotal decimal Net total after discounts and taxes.
salesReturnDiscounts decimal Sum of item-level discounts.
taxable bool Whether tax applies to this return.
applyTaxAfterDiscount bool Whether tax was calculated on the discounted amount.
tax decimal Total tax amount.
cashAmount decimal Cash amount the refund defaults to.
onAccountAmount decimal Amount the refund defaults to crediting to the customer account.
notesReceivableAmount decimal Amount the refund defaults to as a note receivable.
lines List<ReturnableSalesReturnLineResponse> Returnable lines.

SalesPersonReference

Lightweight sales-person reference (id + code + name).

field type description
id int The sales-person id.
code string The sales-person code.
name string The sales-person name.

SalesReturnDiscountType

Discount calculation mode for sales-return line items.

Values (sent/returned as the name): Value=0 (The discount is treated as a fixed value.), Percentage=1 (The discount is treated as a percentage of the line total.)

SalesReturnInstallmentResponse

Response describing a sales-return installment.

field type description
amount decimal? Installment amount.
daysLimit int? Days from document date until due.
dueDate DateTime? Due date.
account AccountReference Account collecting or paying the installment.
paymentType SalesReturnPaymentType? Payment method.

SalesReturnItemResponse

Response describing a sales-return line item.

field type description
id int? Line identifier.
quantity decimal? Quantity returned.
issuedQuantity decimal? Quantity already received back.
unitPrice decimal? Unit price (pre-tax, pre-discount).
price decimal? Line price as charged on the original sale (post-discount, pre-tax).
taxRate decimal? Tax rate from the original sale.
tax TaxReference Tax applied to the line.
itemDiscount decimal? Item discount value.
itemDiscountType SalesReturnDiscountType? Item discount type (value or percentage).
warehouse WarehouseReference Receiving warehouse.
bundleId int? Bundle id, when applicable.
stockItem StockItemReference Returned stock item.
unitOfMeasure UnitOfMeasureReference Unit of measure.
batchNumber string Batch number.
expiryDate DateTime? Batch expiry date.
comments string Free-text line comments.
returnedQuantity decimal? Quantity previously returned against the original sale.
bundleQuantity decimal? Bundle component quantity, when applicable.
relatedSerials List<string> Returned serial numbers, for serialized items.

SalesReturnOrderStatus

Sales-return lifecycle states.

Values (sent/returned as the name): Cancelled=0 (The sales return is cancelled.), Confirmed=1 (The sales return is confirmed.), Pending=2 (The sales return is pending processing.), Processing=3 (The sales return is being processed.), OutForDelivery=4 (The sales return is out for delivery.), Shipped=5 (The sales return has been shipped.), Returned=6 (The sales return was returned by the customer or logistics flow.)

SalesReturnPaymentStatus

Sales-return payment states.

Values (sent/returned as the name): Unpaid=0 (The sales return is unpaid.), PartiallyPaid=1 (The sales return is partially paid.), Paid=2 (The sales return is fully paid.)

SalesReturnPaymentType

Sales-return installment payment methods.

Values (sent/returned as the name): Cash=0 (Payment is collected in cash.), CashOnDelivery=1 (Payment is collected cash on delivery.), OnAccount=2 (Payment is posted on account.)

SalesReturnResponse

Response describing a sales return.

field type description
id int Sales-return identifier.
documentCode string Document code (e.g. "SR-2026-00001").
orderStatus SalesReturnOrderStatus? Lifecycle status.
documentType DocumentType? Document type. Always SR.
paperNumber string Paper / reference number.
runSheetId string Run-sheet identifier.
customer CustomerReference Customer reference.
salesPerson SalesPersonReference Sales person reference.
warehouse WarehouseReference Receiving warehouse.
salesStore SalesStoreReference Sales store / POS location.
shippmentCost decimal? Shipping cost reimbursed.
documentDate DateTime? Document date.
shippingDate DateTime? Expected shipping date.
grossTotal decimal? Gross total, before discounts and taxes.
subTotal decimal? Sub-total after item discounts, before order discount and taxes.
netTotal decimal? Net total after discounts and taxes.
totalItemsDiscounts decimal? Sum of item-level discounts.
discount decimal? Order-level discount amount.
discountRate decimal? Order-level discount percentage.
taxable bool? Whether tax was applied.
applyTaxAfterDiscount bool? Whether tax was calculated on the discounted amount.
tax decimal? Total tax amount.
cashAmount decimal? Cash amount returned.
onAccountAmount decimal? Amount credited to the customer account.
cashPaid decimal? Actual cash paid back.
currency CurrencyReference Settlement currency.
exchangeRate decimal? Exchange rate to system currency.
channel string Sales channel.
notes string Free-text notes.
externalId string External system identifier.
relatedWorkOrderCode string Related issue-offering work-order code.
relatedWorkOrderValue decimal? Value on the related issue-offering work order.
tags List<string> Tags.
relatedSalesReturnCodes List<string> Related sales-return codes.
relatedSalesOrderCodes List<string> Related sales-order codes.
paymentInformation Dictionary<string,decimal> Payment breakdown keyed by method.
salesOrderDetails List<SalesReturnItemResponse> Return lines.
salesOrderInstallments List<SalesReturnInstallmentResponse> Installments.
documentNumber string Sequential document number within the SR series.
fulfillmentDate DateTime? Fulfillment date.
deviceSerial string POS device serial.
addressId int? Customer address id.
addressDescription string Free-text delivery address description.
paymentStatus SalesReturnPaymentStatus? Payment status.
otherCreditAmount decimal? Amount settled via other credit instruments.
isApproved bool Whether the return has been approved.
isIssued bool Whether the return has been issued (stock received).
requireAutoWorkorder bool Whether an auto-generated receiving work order is required.

SalesStoreReference

Lightweight sales-store reference (id + code + name).

field type description
id int The sales-store id.
code string The sales-store code.
name string The sales-store name.

ServiceItemReference

Lightweight reference to a service item.

field type description
id int Service-item identifier.
code string Service-item code.
description string Service-item description.

StockItemReference

Lightweight stock-item reference (id + code + description).

field type description
id int The stock-item id.
code string The stock-item code.
description string The stock-item description.

TaxReference

Lightweight tax reference (id + name + rate).

field type description
id int The tax id.
name string The tax name.
rate decimal The tax rate as a percentage.

UnitOfMeasureReference

Lightweight unit-of-measure reference (id + name).

field type description
id int The unit-of-measure id.
name string The unit-of-measure name.

WarehouseReference

Lightweight warehouse reference (id + code + name).

field type description
id int The warehouse id.
code string The warehouse code.
name string The warehouse name.