/v1/facilities/{facility_id}/retail-salesAuthentication
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 POST \
--url 'https://api.staging.facily.ai/v1/facilities/<FACILITY_ID>/retail-sales' \
--header "Authorization: Bearer $FACILY_API_KEY" \
--header 'Idempotency-Key: <IDEMPOTENCY_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"expected_total": 0,
"lines": [
{
"item_id": "00000000-0000-4000-8000-000000000001",
"quantity": 1,
"discount_amount": "0.00"
}
],
"payer": {
"kind": "string",
"lease_id": "00000000-0000-4000-8000-000000000001"
}
}'Parameters
facility_idpath · stringrequiredFormat: uuid
Idempotency-Keyheader · stringrequiredMin length: 1 · Max length: 100
Request body
application/json · Required
expected_totalnumber | stringrequiredThe total the caller showed, from the quote. A different total now is refused.
Minimum: 0 · Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
Show expected_total schema
number | stringThe total the caller showed, from the quote. A different total now is refused.
Variant 1: number
numberVariant 2: string
stringlinesSaleLineRequest[]requiredThe items and quantities. At least one.
Min items: 1
Show lines schema
discount_amountnumber | stringDollars taken off the line at the till, at most its quantity times the unit price; tax is on what is left. Needs retail.discount.
Default: "0.00" · Minimum: 0 · Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,8}|(?=[\d.]{1,11}0*$)\d{0,8}\.\d{0,2}0*$)
Show discount_amount schema
number | stringDollars taken off the line at the till, at most its quantity times the unit price; tax is on what is left. Needs retail.discount.
Variant 1: number
numberVariant 2: string
stringitem_idstringrequiredThe catalog item sold.
Format: uuid
quantityintegerrequiredUnits sold. Lines naming the same item are added together.
Minimum: 1
payerTenantPayerRequest | WalkInPayerRequestrequiredWho pays: a tenant on their lease's ledger, or a walk-in paying now on the counter.
Show payer schema
TenantPayerRequest | WalkInPayerRequestWho pays: a tenant on their lease's ledger, or a walk-in paying now on the counter.
Variant 1: TenantPayerRequest
kindstringrequiredA tenant: the sale is charged to the lease's ledger.
lease_idstringrequiredThe active lease the charge posts to.
Format: uuid
Variant 2: WalkInPayerRequest
expected_surcharge_amountnumber | string | nullKeyed card only: the surcharge the operator was shown. A different quote now is refused.
Minimum: 0 · Pattern: ^(?!^[-+.]*$)[+-]?0*(?:\d{0,10}|(?=[\d.]{1,13}0*$)\d{0,10}\.\d{0,2}0*$)
Show expected_surcharge_amount schema
number | string | nullKeyed card only: the surcharge the operator was shown. A different quote now is refused.
Variant 1: number
numberVariant 2: string
stringVariant 3: null
nullexternal_referencestring | nullA card run elsewhere: its reference. A check or money order: its number (required). Refused for cash. The rules are the payments route's.
Max length: 255
Show external_reference schema
string | nullA card run elsewhere: its reference. A check or money order: its number (required). Refused for cash. The rules are the payments route's.
Variant 1: string
stringVariant 2: null
nullkindstringrequiredSomeone who is not a tenant, paying at the counter.
payment_method_idstring | nullCard only: a one-time card vaulted for this sale (POST .../one-time-cards), charged now.
Format: uuid
Show payment_method_id schema
string | nullCard only: a one-time card vaulted for this sale (POST .../one-time-cards), charged now.
Variant 1: string
stringVariant 2: null
nulltenderstringrequiredHow the walk-in pays. A card names exactly one of payment_method_id, terminal_id or external_reference.
Values: "cash", "card", "check", "money_order"
terminal_idstring | nullCard only: the reader that takes the card.
Format: uuid
Show terminal_id schema
string | nullCard only: the reader that takes the card.
Variant 1: string
stringVariant 2: null
nullResponses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
201Successful 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_idstringrequired202The card is at the processor: the sale is pending (or void_pending) until it decides
{
"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