/v1/retail-sales/{sale_id}Authentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest example
Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.
curl --request GET \
--url 'https://api.staging.facily.ai/v1/retail-sales/<SALE_ID>' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
sale_idpath · stringrequiredFormat: uuid
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"data": {
"can_void": false,
"created_at": "2026-10-29T12:00:00Z",
"discount_amount": "<VALUE_MATCHING_PATTERN>",
"facility_id": "00000000-0000-4000-8000-000000000001",
"id": "00000000-0000-4000-8000-000000000001",
"lines": [
{
"discount_amount": "<VALUE_MATCHING_PATTERN>",
"item_id": "00000000-0000-4000-8000-000000000001",
"name": "string",
"quantity": 0,
"sku": "string",
"subtotal": "<VALUE_MATCHING_PATTERN>",
"tax_amount": "<VALUE_MATCHING_PATTERN>",
"total": "<VALUE_MATCHING_PATTERN>",
"unit_price": "<VALUE_MATCHING_PATTERN>"
}
],
"payer_kind": "string",
"payment_id": "00000000-0000-4000-8000-000000000001",
"sold_on": "2026-10-29",
"staff_name": "string",
"status": "string",
"subtotal": "<VALUE_MATCHING_PATTERN>",
"tax_amount": "<VALUE_MATCHING_PATTERN>",
"tenant": {
"id": "00000000-0000-4000-8000-000000000001",
"name": "string"
},
"tender": {
"last_four": "string",
"method": "string",
"reference": "string"
},
"total": "<VALUE_MATCHING_PATTERN>",
"unit_numbers": [
"string"
],
"void_blocked_reason": "string"
},
"meta": {
"request_id": "string"
}
}application/json
dataSaleResponserequiredShow data schema
can_voidbooleanrequiredWhether this caller can void the sale now: holds the permissions for its payer kind, the sale is completed, and the facility's void window is open.
created_atstringrequiredWhen the sale was made.
Format: date-time
discount_amountstringrequiredThe lines' discounts added up.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
facility_idstringrequiredThe facility that made the sale.
Format: uuid
idstringrequiredUnique identifier for this sale.
Format: uuid
linesSaleListLineResponse[]requiredOne line per item.
Show lines schema
discount_amountstringrequiredTaken off the line at the till; 0.00 when none.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
item_idstringrequiredThe catalog item.
Format: uuid
namestringrequiredThe item's name.
quantityintegerrequiredUnits sold.
skustringrequiredThe item's SKU.
subtotalstringrequiredQuantity times the unit price.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
tax_amountstringrequiredTax on the line after its discount; 0.00 when untaxed.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
totalstringrequiredSubtotal less the discount, plus tax.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
unit_pricestringrequiredThe price of one unit when sold.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
payer_kindstringrequiredtenant or walk_in.
payment_idstring | nullrequiredThe walk-in's payment.
Format: uuid
Show payment_id schema
string | nullThe walk-in's payment.
Variant 1: string
stringVariant 2: null
nullsold_onstringrequiredThe facility's business date of the sale.
Format: date
staff_namestring | nullrequiredWho made the sale.
Show staff_name schema
string | nullWho made the sale.
Variant 1: string
stringVariant 2: null
nullstatusstringrequiredcompleted, void_pending or voided.
subtotalstringrequiredThe lines' subtotals added up.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
tax_amountstringrequiredThe lines' tax added up.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
tenantSaleTenantResponse | nullrequiredThe tenant, for a tenant sale; null for a walk-in.
Show tenant schema
SaleTenantResponse | nullThe tenant, for a tenant sale; null for a walk-in.
Variant 1: SaleTenantResponse
idstringrequiredThe tenant.
Format: uuid
namestringrequiredThe tenant's name as staff see it.
Variant 2: null
nulltenderSaleTenderResponse | nullrequiredHow a walk-in paid; null for a tenant sale.
Show tender schema
SaleTenderResponse | nullHow a walk-in paid; null for a tenant sale.
Variant 1: SaleTenderResponse
last_fourstring | nullrequiredA card's last four digits, when the sale kept the card.
Show last_four schema
string | nullA card's last four digits, when the sale kept the card.
Variant 1: string
Variant 2: null
methodstringrequiredcash, check, money_order or card.
referencestring | nullrequiredA check or money order number, or a card's outside reference.
Show reference schema
string | nullA check or money order number, or a card's outside reference.
Variant 1: string
Variant 2: null
Variant 2: null
nulltotalstringrequiredWhat the sale charged.
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
unit_numbersstring[]requiredThe tenant's unit, for a tenant sale; empty for a walk-in.
Show unit_numbers schema
stringvoid_blocked_reasonstring | nullrequiredWhy a completed sale cannot be voided: void_window_closed or lease_not_active; else null.
Show void_blocked_reason schema
string | nullWhy a completed sale cannot be voided: void_window_closed or lease_not_active; else null.
Variant 1: string
stringVariant 2: null
nullmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired