{ "openapi": "3.0.0", "paths": { "/v1/discounts": { "get": { "description": "Lists the discounts a cashier can apply at the register, newest first.", "operationId": "listDiscounts", "parameters": [ { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 100, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "type", "required": false, "in": "query", "style": "form", "explode": true, "description": "How the discount reduces the price. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "amount_off", "percentage_off" ] } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscountList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List discounts", "tags": [ "Discounts" ], "x-vori-required-permission": { "resource": "discounts", "action": "read", "granularity": "banner" } }, "post": { "description": "Creates a discount a cashier can apply at the register.", "operationId": "createDiscount", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDiscountRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discount" } } } }, "400": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a discount", "tags": [ "Discounts" ], "x-vori-required-permission": { "resource": "discounts", "action": "create", "granularity": "banner" } } }, "/v1/discounts/{id}": { "delete": { "description": "Deletes a discount. A cashier can no longer apply it.", "operationId": "deleteDiscount", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "204": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a discount", "tags": [ "Discounts" ], "x-vori-required-permission": { "resource": "discounts", "action": "delete", "granularity": "banner" } }, "get": { "operationId": "getDiscount", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discount" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a discount", "tags": [ "Discounts" ], "x-vori-required-permission": { "resource": "discounts", "action": "read", "granularity": "banner" }, "description": "Retrieve a discount" }, "patch": { "description": "Updates the properties the request supplies.", "operationId": "updateDiscount", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDiscountRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Discount" } } } }, "400": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a discount", "tags": [ "Discounts" ], "x-vori-required-permission": { "resource": "discounts", "action": "update", "granularity": "banner" } } }, "/v1/employees": { "get": { "description": "Lists employees, newest first.", "operationId": "listEmployees", "parameters": [ { "name": "active", "required": false, "in": "query", "description": "Whether the employee has not been deactivated.", "schema": { "type": "boolean" } }, { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Credentials to return on each employee. Neither is returned by default. Repeat the parameter to request both, for example `?include=pin&include=badge_barcode`.\n\nRequesting a credential without the employees:read_credentials permission is rejected rather than silently omitted.\n\n- `pin` — returns `pin`, the PIN the employee signs in with.\n- `badge_barcode` — returns `badge_barcode`, the badge the employee scans to sign in.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeCredential" } } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List employees", "tags": [ "Employees" ], "x-vori-required-permission": { "resource": "employees", "action": "read", "granularity": "banner" } }, "post": { "description": "Creates an employee who can sign in at the point of sale and be credited for the orders they ring up.", "operationId": "createEmployee", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmployeeRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employee" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PinAlreadyAssignedError" }, { "$ref": "#/components/schemas/BarcodeAlreadyAssignedError" }, { "$ref": "#/components/schemas/EmailAddressAlreadyAssignedError" }, { "$ref": "#/components/schemas/MissingCredentialsForAuthenticationRuleError" }, { "$ref": "#/components/schemas/InvalidAuthenticationRuleError" }, { "$ref": "#/components/schemas/InvalidEmployeeRoleError" }, { "$ref": "#/components/schemas/InvalidStoreError" }, { "$ref": "#/components/schemas/DeactivatedEmployeeCredentialsError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create an employee", "tags": [ "Employees" ], "x-vori-required-permission": { "resource": "employees", "action": "create", "granularity": "banner" } } }, "/v1/employees/{id}": { "delete": { "description": "Deactivates an employee. The record is retained so past orders and reporting still resolve the employee they name, and the employee's PIN and barcode are cleared so another employee can take them. Employees can be reactivated by setting `deactivated_at` to `null` via the update operation.", "operationId": "deleteEmployee", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EmployeeNotUserEditableError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Deactivate an employee", "tags": [ "Employees" ], "x-vori-required-permission": { "resource": "employees", "action": "delete", "granularity": "banner" } }, "get": { "operationId": "getEmployee", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Credentials to return on each employee. Neither is returned by default. Repeat the parameter to request both, for example `?include=pin&include=badge_barcode`.\n\nRequesting a credential without the employees:read_credentials permission is rejected rather than silently omitted.\n\n- `pin` — returns `pin`, the PIN the employee signs in with.\n- `badge_barcode` — returns `badge_barcode`, the badge the employee scans to sign in.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EmployeeCredential" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employee" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve an employee", "tags": [ "Employees" ], "x-vori-required-permission": { "resource": "employees", "action": "read", "granularity": "banner" }, "description": "Retrieve an employee" }, "patch": { "description": "Updates an employee. Properties the request does not name are left unchanged, and passing `null` clears one. Supplying `roles` replaces every role the employee holds.", "operationId": "updateEmployee", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmployeeRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Employee" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PinAlreadyAssignedError" }, { "$ref": "#/components/schemas/BarcodeAlreadyAssignedError" }, { "$ref": "#/components/schemas/EmailAddressAlreadyAssignedError" }, { "$ref": "#/components/schemas/MissingCredentialsForAuthenticationRuleError" }, { "$ref": "#/components/schemas/InvalidAuthenticationRuleError" }, { "$ref": "#/components/schemas/InvalidEmployeeRoleError" }, { "$ref": "#/components/schemas/InvalidStoreError" }, { "$ref": "#/components/schemas/DeactivatedEmployeeCredentialsError" }, { "$ref": "#/components/schemas/EmployeeNotUserEditableError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update an employee", "tags": [ "Employees" ], "x-vori-required-permission": { "resource": "employees", "action": "update", "granularity": "banner" } } }, "/v1/item-modifiers": { "get": { "description": "Lists item modifiers, newest first, across every store you can read.", "operationId": "listItemModifiers", "parameters": [ { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 100, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "ID of the store the item modifier belongs to. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "type", "required": false, "in": "query", "style": "form", "explode": true, "description": "Business purpose of the item modifier. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "bottle_deposit", "custom", "food_modifier" ] } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemModifierList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List item modifiers", "tags": [ "Item modifiers" ], "x-vori-required-permission": { "resource": "item_modifiers", "action": "read", "granularity": "store" } }, "post": { "operationId": "createItemModifier", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateItemModifierRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemModifier" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingPropertyValuesError" }, { "$ref": "#/components/schemas/InvalidStoreError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create an item modifier", "tags": [ "Item modifiers" ], "x-vori-required-permission": { "resource": "item_modifiers", "action": "create", "granularity": "store" }, "description": "Create an item modifier" } }, "/v1/item-modifiers/{id}": { "delete": { "operationId": "deleteItemModifier", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ItemModifierInUseError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete an item modifier", "tags": [ "Item modifiers" ], "x-vori-required-permission": { "resource": "item_modifiers", "action": "delete", "granularity": "store" }, "description": "Delete an item modifier" }, "get": { "operationId": "getItemModifier", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemModifier" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve an item modifier", "tags": [ "Item modifiers" ], "x-vori-required-permission": { "resource": "item_modifiers", "action": "read", "granularity": "store" }, "description": "Retrieve an item modifier" }, "patch": { "operationId": "updateItemModifier", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateItemModifierRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemModifier" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingPropertyValuesError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update an item modifier", "tags": [ "Item modifiers" ], "x-vori-required-permission": { "resource": "item_modifiers", "action": "update", "granularity": "store" }, "description": "Update an item modifier" } }, "/v1/lanes": { "get": { "operationId": "listLanes", "parameters": [ { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 50, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The store the lane is located in. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "virtual", "required": false, "in": "query", "description": "Whether the lane exists only to attribute orders rather than ring up a sale. Omit to match both kinds.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaneList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/UnauthorizedBannerError" }, { "$ref": "#/components/schemas/UnauthorizedStoreError" }, { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List lanes", "tags": [ "Lanes" ], "x-vori-required-permission": { "resource": "lanes", "action": "read", "granularity": "store" }, "description": "List lanes" } }, "/v1/lanes/{id}": { "get": { "operationId": "getLane", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lane" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a lane", "tags": [ "Lanes" ], "x-vori-required-permission": { "resource": "lanes", "action": "read", "granularity": "store" }, "description": "Retrieve a lane" } }, "/v1/shoppers": { "get": { "description": "Lists shoppers across the whole banner, ordered by ID. Filter by phone number to find the shopper who gave it at checkout, and page through the results with the cursor parameters.", "operationId": "listShoppers", "parameters": [ { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "type": "string" } }, { "name": "enrolled_in_loyalty_program", "required": false, "in": "query", "description": "Whether the shopper is enrolled in the loyalty program.", "schema": { "type": "boolean" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "phone_number", "required": false, "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Phone number on file for the shopper. Matched exactly." }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShopperList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "402": { "description": "The required capability is not enabled for the banner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityRequiredException" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List shoppers", "tags": [ "Shoppers" ], "x-vori-required-capability": "loyalty_rewards", "x-vori-required-permission": { "resource": "shoppers", "action": "read", "granularity": "banner" } }, "post": { "operationId": "createShopper", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateShopperRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shopper" } } } }, "400": { "description": "" }, "402": { "description": "The required capability is not enabled for the banner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityRequiredException" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a shopper", "tags": [ "Shoppers" ], "x-vori-required-capability": "loyalty_rewards", "x-vori-required-permission": { "resource": "shoppers", "action": "create", "granularity": "banner" }, "description": "Create a shopper" } }, "/v1/shoppers/{id}": { "get": { "operationId": "getShopper", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shopper" } } } }, "402": { "description": "The required capability is not enabled for the banner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityRequiredException" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a shopper", "tags": [ "Shoppers" ], "x-vori-required-capability": "loyalty_rewards", "x-vori-required-permission": { "resource": "shoppers", "action": "read", "granularity": "banner" }, "description": "Retrieve a shopper" }, "patch": { "operationId": "updateShopper", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShopperRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Shopper" } } } }, "400": { "description": "" }, "402": { "description": "The required capability is not enabled for the banner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapabilityRequiredException" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a shopper", "tags": [ "Shoppers" ], "x-vori-required-capability": "loyalty_rewards", "x-vori-required-permission": { "resource": "shoppers", "action": "update", "granularity": "banner" }, "description": "Update a shopper" } }, "/v1/store-departments": { "get": { "description": "Lists the departments a store organizes its products into, newest first.", "operationId": "listStoreDepartments", "parameters": [ { "name": "active", "required": false, "in": "query", "description": "Whether the department has not been deactivated.", "schema": { "type": "boolean" } }, { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "parent_department_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The parent department a sub-department belongs to. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The store the department belongs to. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDepartmentList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" }, { "$ref": "#/components/schemas/InvalidStoresError" }, { "$ref": "#/components/schemas/InvalidStoreError" }, { "$ref": "#/components/schemas/MissingStoreError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List store departments", "tags": [ "Departments" ], "x-vori-required-permission": { "resource": "departments", "action": "read", "granularity": "store" } }, "post": { "description": "Creates a department in a store. Pass `parent_department_id` to create a sub-department of an existing top-level department.", "operationId": "createStoreDepartment", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStoreDepartmentRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDepartment" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidStoreError" }, { "$ref": "#/components/schemas/InvalidParentDepartmentError" }, { "$ref": "#/components/schemas/InvalidDepartmentHierarchyError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a store department", "tags": [ "Departments" ], "x-vori-required-permission": { "resource": "departments", "action": "create", "granularity": "store" } } }, "/v1/store-departments/{id}": { "get": { "operationId": "getStoreDepartment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDepartment" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a store department", "tags": [ "Departments" ], "x-vori-required-permission": { "resource": "departments", "action": "read", "granularity": "store" }, "description": "Retrieve a store department" }, "patch": { "description": "Updates a department. Stamping `deactivated_at` deactivates it and setting it back to null reactivates it; a deactivated department is retained so reporting and past orders still resolve the department they name. A department is only deactivated once it has no active products and no active sub-departments.", "operationId": "updateStoreDepartment", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStoreDepartmentRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDepartment" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidParentDepartmentError" }, { "$ref": "#/components/schemas/InvalidDepartmentHierarchyError" }, { "$ref": "#/components/schemas/DepartmentHasActiveProductsError" }, { "$ref": "#/components/schemas/DepartmentHasActiveSubDepartmentsError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a store department", "tags": [ "Departments" ], "x-vori-required-permission": { "resource": "departments", "action": "update", "granularity": "store" } } }, "/v1/store-product-inventory": { "get": { "description": "Lists the current on-hand quantity for each store product. Filter by `updated_at` to retrieve only the products counted since a previous request.", "operationId": "listStoreProductInventory", "parameters": [ { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "store_department_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The department the product belongs to. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "store_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The store the product belongs to. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "updated_at", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the on-hand quantity was last written. Pair a lower bound with a page size to poll for products counted since the previous request. UTC unless the value carries an offset." }, { "name": "updated_at[gt]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the on-hand quantity was last written. Pair a lower bound with a page size to poll for products counted since the previous request. UTC unless the value carries an offset." }, { "name": "updated_at[gte]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the on-hand quantity was last written. Pair a lower bound with a page size to poll for products counted since the previous request. UTC unless the value carries an offset." }, { "name": "updated_at[lt]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the on-hand quantity was last written. Pair a lower bound with a page size to poll for products counted since the previous request. UTC unless the value carries an offset." }, { "name": "updated_at[lte]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the on-hand quantity was last written. Pair a lower bound with a page size to poll for products counted since the previous request. UTC unless the value carries an offset." } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductInventoryList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List store product inventory", "tags": [ "Inventory" ], "x-vori-required-permission": { "resource": "products", "action": "read", "granularity": "store" } }, "post": { "description": "Sets or adjusts the on-hand quantity for the selected products, their reorder levels, or both. Every product a request names must resolve, or nothing is written.", "operationId": "upsertStoreProductInventory", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertStoreProductInventoryRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertStoreProductInventoryResponse" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidStoreProductsError" }, { "$ref": "#/components/schemas/MissingStoreProductSelectionError" }, { "$ref": "#/components/schemas/MultipleBannersSelectedError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientPermissionsError" } } } } }, "security": [ { "bearer": [] } ], "summary": "Update store product inventory", "tags": [ "Inventory" ], "x-vori-required-permission": { "resource": "products", "action": "update", "granularity": "store" } } }, "/v1/store-products": { "get": { "description": "Lists store products, newest first. Page with `limit` and `starting_after` / `ending_before`, and narrow the results with the filter parameters below. The `state` parameter offers a wider set of filters and its own sorting, and cannot be combined with either.", "operationId": "listStoreProducts", "parameters": [ { "name": "active", "required": false, "in": "query", "description": "Whether the product is sellable.", "schema": { "type": "boolean" } }, { "name": "ecommerce_enabled", "required": false, "in": "query", "description": "Whether the product is available for online ordering.", "schema": { "type": "boolean" } }, { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Comma-separated list of related data to include on each product:\n\n- `active_vendor` — Populates `active_vendor` with the product's primary vendor.\n- `active_vendor_product` — Populates `active_vendor_product` with the primary vendor's catalog entry, including costs.\n- `inventory` — Populates `inventory` with on-hand quantity data.\n- `store_vendor_products` — Populates `store_vendor_products` with every vendor's catalog entry for the product.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreProductLoaders" } } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "store_department_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The department the product is assigned to. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "store_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The store the product belongs to. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" }, { "$ref": "#/components/schemas/InvalidStoresError" }, { "$ref": "#/components/schemas/UnsupportedStateFieldError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List store products", "tags": [ "Store products" ], "x-vori-required-permission": { "resource": "products", "action": "read", "granularity": "store" } }, "post": { "operationId": "createStoreProduct", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStoreProductRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProduct" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DuplicateBarcodeTypesForProductError" }, { "$ref": "#/components/schemas/DuplicateBarcodesError" }, { "$ref": "#/components/schemas/InvalidBarcodeError" }, { "$ref": "#/components/schemas/InvalidDepartmentError" }, { "$ref": "#/components/schemas/InvalidFoodModifiersError" }, { "$ref": "#/components/schemas/InvalidItemModifiersError" }, { "$ref": "#/components/schemas/InvalidTaxRatesError" }, { "$ref": "#/components/schemas/InvalidUnitOfMeasureError" }, { "$ref": "#/components/schemas/InvalidVariableWeightsError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a store product", "tags": [ "Store products" ], "x-vori-required-permission": { "resource": "products", "action": "create", "granularity": "store" }, "description": "Create a store product" } }, "/v1/store-products/{id}": { "get": { "operationId": "getStoreProduct", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "include", "required": false, "in": "query", "description": "Comma-separated list of related data to include on each product:\n\n- `active_vendor` — Populates `active_vendor` with the product's primary vendor.\n- `active_vendor_product` — Populates `active_vendor_product` with the primary vendor's catalog entry, including costs.\n- `inventory` — Populates `inventory` with on-hand quantity data.\n- `store_vendor_products` — Populates `store_vendor_products` with every vendor's catalog entry for the product.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/StoreProductLoaders" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProduct" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a store product", "tags": [ "Store products" ], "x-vori-required-permission": { "resource": "products", "action": "read", "granularity": "store" }, "description": "Retrieve a store product" }, "patch": { "operationId": "updateStoreProduct", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStoreProductRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProduct" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/DuplicateBarcodeTypesForProductError" }, { "$ref": "#/components/schemas/DuplicateBarcodesError" }, { "$ref": "#/components/schemas/InvalidBarcodeError" }, { "$ref": "#/components/schemas/InvalidDepartmentError" }, { "$ref": "#/components/schemas/InvalidFoodModifiersError" }, { "$ref": "#/components/schemas/InvalidItemModifiersError" }, { "$ref": "#/components/schemas/InvalidTaxRatesError" }, { "$ref": "#/components/schemas/InvalidUnitOfMeasureError" }, { "$ref": "#/components/schemas/InvalidVariableWeightsError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a store product", "tags": [ "Store products" ], "x-vori-required-permission": { "resource": "products", "action": "update", "granularity": "store" }, "description": "Update a store product" } }, "/v1/store-products/{id}/restore": { "post": { "operationId": "restoreStoreProduct", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProduct" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientPermissionsError" } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Restore a store product", "tags": [ "Store products" ], "x-vori-required-permission": { "resource": "products", "action": "update", "granularity": "store" }, "description": "Restore a store product" } }, "/v1/stores": { "get": { "description": "Lists the stores you can access, newest first.", "operationId": "listStores", "parameters": [ { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List stores", "tags": [ "Stores" ], "x-vori-required-permission": { "resource": "stores", "action": "read", "granularity": "store" } } }, "/v1/stores/{id}": { "get": { "operationId": "getStore", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Store" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a store", "tags": [ "Stores" ], "x-vori-required-permission": { "resource": "stores", "action": "read", "granularity": "store" }, "description": "Retrieve a store" } }, "/v1/tax-rates": { "get": { "description": "Lists the tax rates configured for the banner, newest first.", "operationId": "listTaxRates", "parameters": [ { "name": "active", "required": false, "in": "query", "description": "Whether the rate is charged at checkout.", "schema": { "type": "boolean" } }, { "name": "category", "required": false, "in": "query", "style": "form", "explode": true, "description": "The kind of tax the rate represents. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "other", "sales" ] } } }, { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRateList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List tax rates", "tags": [ "Tax rates" ], "x-vori-required-permission": { "resource": "tax_rates", "action": "read", "granularity": "banner" } }, "post": { "description": "Adds a tax rate to the banner.", "operationId": "createTaxRate", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaxRateRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "400": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a tax rate", "tags": [ "Tax rates" ], "x-vori-required-permission": { "resource": "tax_rates", "action": "create", "granularity": "banner" } } }, "/v1/tax-rates/{id}": { "get": { "operationId": "getTaxRate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a tax rate", "tags": [ "Tax rates" ], "x-vori-required-permission": { "resource": "tax_rates", "action": "read", "granularity": "banner" }, "description": "Retrieve a tax rate" }, "patch": { "description": "Updates the supplied fields on a tax rate. Omitted fields are left unchanged.", "operationId": "updateTaxRate", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaxRateRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxRate" } } } }, "400": { "description": "" }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a tax rate", "tags": [ "Tax rates" ], "x-vori-required-permission": { "resource": "tax_rates", "action": "update", "granularity": "banner" } } }, "/v1/transactions": { "get": { "description": "Lists transactions across your stores, ordered by transaction ID. Filter by store and completion time to pull a window of sales, and page through the results with the cursor parameters.", "operationId": "listTransactions", "parameters": [ { "name": "completed_at", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the transaction was completed. UTC unless the value carries an offset." }, { "name": "completed_at[gt]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the transaction was completed. UTC unless the value carries an offset." }, { "name": "completed_at[gte]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the transaction was completed. UTC unless the value carries an offset." }, { "name": "completed_at[lt]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the transaction was completed. UTC unless the value carries an offset." }, { "name": "completed_at[lte]", "required": false, "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "When the transaction was completed. UTC unless the value carries an offset." }, { "name": "employee_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The cashier who completed the transaction. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "type": "string" } }, { "name": "external_id", "required": false, "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "Your own identifier for the transaction. Matched exactly." }, { "name": "lane_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The lane the transaction was completed on. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "shopper_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The identified shopper, for transactions that had one. Accepts a TypeID or a UUID. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "type": "string" } }, { "name": "status", "required": false, "in": "query", "style": "form", "explode": true, "description": "Lifecycle status of the transaction. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "completed", "expired", "suspended", "voided" ] } } }, { "name": "store_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "The store where the transaction was completed. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "type", "required": false, "in": "query", "style": "form", "explode": true, "description": "Whether the transaction is a sale, a refund, or a void. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "refund", "sale", "void" ] } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionsList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List transactions", "tags": [ "Transactions" ], "x-vori-required-permission": { "resource": "pos_orders", "action": "read", "granularity": "store" } }, "post": { "description": "Records a transaction your own system processed, such as an order taken on your website. Send a UUIDv7 as `id`; sending the same transaction again under that ID returns the transaction already recorded rather than creating a second, and sending different values under it is rejected. Only `store_id` is needed to attribute the transaction: Vori maintains a lane and an employee for this purpose and records it against them.", "operationId": "createTransaction", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InvalidStoreError" }, { "$ref": "#/components/schemas/TransactionLaneNotFoundError" }, { "$ref": "#/components/schemas/TransactionLaneStoreMismatchError" }, { "$ref": "#/components/schemas/TransactionLaneNotVirtualError" }, { "$ref": "#/components/schemas/TransactionEmployeeNotFoundError" }, { "$ref": "#/components/schemas/TransactionEmployeeNotVirtualError" }, { "$ref": "#/components/schemas/TransactionShopperNotFoundError" }, { "$ref": "#/components/schemas/TransactionStoreProductsNotFoundError" }, { "$ref": "#/components/schemas/TransactionItemModifiersNotFoundError" }, { "$ref": "#/components/schemas/TransactionTotalsMismatchError" }, { "$ref": "#/components/schemas/TransactionLineItemInvalidError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransactionAlreadyExistsError" }, { "$ref": "#/components/schemas/TransactionRequestMismatchError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a transaction", "tags": [ "Transactions" ], "x-vori-required-permission": { "resource": "pos_orders", "action": "create", "granularity": "store" } } }, "/v1/transactions/{id}": { "get": { "description": "Retrieves one transaction with its line items, payments, and a reference to each of its refunds. Related records come back as IDs.", "operationId": "getTransaction", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a transaction", "tags": [ "Transactions" ], "x-vori-required-permission": { "resource": "pos_orders", "action": "read", "granularity": "store" } } }, "/v1/transactions/{id}/refunds": { "post": { "description": "Records a refund your own system processed against a transaction Vori already recorded, and returns it as a transaction of its own. Only a transaction created through this API can be refunded. Quantities and amounts are negative, as they are when you read a refund back, and a line cannot return more than it has left after earlier refunds. Send a UUIDv7 as `id`; sending the same refund again under that ID returns the refund already recorded rather than creating a second, and sending different values under it is rejected.", "operationId": "createTransactionRefund", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "format": "uuid", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransactionLaneNotFoundError" }, { "$ref": "#/components/schemas/TransactionLaneStoreMismatchError" }, { "$ref": "#/components/schemas/TransactionLaneNotVirtualError" }, { "$ref": "#/components/schemas/TransactionEmployeeNotFoundError" }, { "$ref": "#/components/schemas/TransactionEmployeeNotVirtualError" }, { "$ref": "#/components/schemas/TransactionTotalsMismatchError" }, { "$ref": "#/components/schemas/TransactionLineItemInvalidError" }, { "$ref": "#/components/schemas/RefundTransactionNotRefundableError" }, { "$ref": "#/components/schemas/RefundLineItemsNotFoundError" }, { "$ref": "#/components/schemas/RefundPaymentsNotFoundError" }, { "$ref": "#/components/schemas/RefundExceedsOriginalError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransactionAlreadyExistsError" }, { "$ref": "#/components/schemas/TransactionRequestMismatchError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Refund a transaction", "tags": [ "Transactions" ], "x-vori-required-permission": { "resource": "pos_orders", "action": "create", "granularity": "store" } } }, "/v1/variable-weights": { "get": { "description": "Lists variable weights, newest first, across every store you can read.", "operationId": "listVariableWeights", "parameters": [ { "name": "ending_before", "required": false, "in": "query", "description": "Return records that precede the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Maximum number of records to return.", "schema": { "minimum": 1, "maximum": 100, "default": 100, "type": "integer" } }, { "name": "starting_after", "required": false, "in": "query", "description": "Return records that follow the record with this ID, in list order.", "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "name": "store_id", "required": false, "in": "query", "style": "form", "explode": true, "description": "ID of the store the variable weight belongs to. Variable weights are not shared between stores. Repeat to match any of up to 20 values.", "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariableWeightList" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingListParametersError" }, { "$ref": "#/components/schemas/InvalidListCursorError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "List variable weights", "tags": [ "Variable weights" ], "x-vori-required-permission": { "resource": "variable_weights", "action": "read", "granularity": "store" } }, "post": { "operationId": "createVariableWeight", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVariableWeightRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariableWeight" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingPropertyValuesError" }, { "$ref": "#/components/schemas/InvalidStoreError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } } }, "security": [ { "bearer": [] } ], "summary": "Create a variable weight", "tags": [ "Variable weights" ], "x-vori-required-permission": { "resource": "variable_weights", "action": "create", "granularity": "store" }, "description": "Create a variable weight" } }, "/v1/variable-weights/{id}": { "delete": { "operationId": "deleteVariableWeight", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "204": { "description": "" }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/VariableWeightInUseError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Delete a variable weight", "tags": [ "Variable weights" ], "x-vori-required-permission": { "resource": "variable_weights", "action": "delete", "granularity": "store" }, "description": "Delete a variable weight" }, "get": { "operationId": "getVariableWeight", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariableWeight" } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Retrieve a variable weight", "tags": [ "Variable weights" ], "x-vori-required-permission": { "resource": "variable_weights", "action": "read", "granularity": "store" }, "description": "Retrieve a variable weight" }, "patch": { "operationId": "updateVariableWeight", "parameters": [ { "name": "id", "required": true, "in": "path", "schema": { "pattern": "^[0-9]+$", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVariableWeightRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariableWeight" } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConflictingPropertyValuesError" } ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsufficientPermissionsError" }, { "$ref": "#/components/schemas/NoBannerAssociationError" } ] } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ], "summary": "Update a variable weight", "tags": [ "Variable weights" ], "x-vori-required-permission": { "resource": "variable_weights", "action": "update", "granularity": "store" }, "description": "Update a variable weight" } } }, "info": { "title": "Vori API", "description": "", "version": "1.0.0", "contact": {} }, "tags": [], "servers": [ { "url": "https://api.vori.com", "description": "production" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "Action": { "type": "string", "enum": [ "*", "cancel", "check_in", "create", "delete", "read", "read_credentials", "record_events", "refund", "restart", "update", "void" ] }, "AssignableRoleName": { "type": "string", "enum": [ "manager" ] }, "AuthenticationMethod": { "type": "string", "enum": [ "barcode", "pin" ] }, "AuthenticationRule": { "type": "object", "properties": { "methods": { "type": "array", "minItems": 1, "description": "The credentials the employee presents to sign in. Never empty, and every method named must have its credential set on the employee, whichever operator the rule uses.", "items": { "$ref": "#/components/schemas/AuthenticationMethod" } }, "operator": { "description": "How the methods combine: `and` requires every one of them, `or` requires any one of them.", "allOf": [ { "$ref": "#/components/schemas/AuthenticationRuleOperator" } ] } }, "description": "How an employee proves their identity at the point of sale. An active employee with no rule of their own authenticates with a PIN.", "required": [ "methods", "operator" ] }, "AuthenticationRuleOperator": { "type": "string", "enum": [ "and", "or" ] }, "BarcodeAlreadyAssignedError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "barcode_already_assigned" ] } }, "required": [ "error_code" ] }, "BarcodeIdentifier": { "type": "object", "properties": { "barcode": { "type": "string" }, "type": { "allOf": [ { "$ref": "#/components/schemas/StoreVendorProductIdentifierType" } ] } }, "required": [ "barcode", "type" ] }, "BarcodeType": { "type": "string", "enum": [ "EAN 13 Type 2 Without Check Digit", "EAN-13", "EAN-13 Without Check Digit", "EAN-14", "EAN-14 Without Check Digit", "EAN-8", "EAN-8 Without Check Digit", "PLU", "PRODUCE PLU", "Type 2 EAN", "Type 2 UPC", "Unsanitized", "UPC Shipping Container", "UPC-A", "UPC-A Type 2 Without Check Digit", "UPC-A Without Check Digit", "UPC-E", "UPC-E Without Check Digit" ] }, "CapabilityRequiredException": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "capability_not_enabled" ] } }, "required": [ "error_code" ] }, "CardBrand": { "type": "string", "enum": [ "american_express", "atm", "bill_me_later", "china_union_pay", "debit", "diners_club", "discover", "ebt", "jcb", "mastercard", "other", "revolution_money", "telecheck", "undetermined", "visa", "voyager", "wright_express" ] }, "CompactFoodModifierCategory": { "type": "object", "properties": { "id": { "type": "string" }, "max_selection": { "type": "integer", "description": "Maximum number of options customer can select", "nullable": true }, "min_selection": { "type": "integer", "description": "Minimum number of options customer must select (0 = no minimum)" }, "modifiers": { "description": "Modifiers assigned to this product in this category", "type": "array", "items": { "$ref": "#/components/schemas/FoodModifier" } }, "name": { "type": "string", "description": "Category name" }, "priority": { "type": "integer", "description": "Display priority (lower = shown first)" } }, "required": [ "id", "max_selection", "min_selection", "modifiers", "name", "priority" ] }, "CompactItemModifier": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the item modifier." }, "name": { "type": "string", "description": "Human-readable item modifier name." }, "tax_behavior": { "description": "Whether the modifier is excluded from tax or inherits the product tax behavior.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierTaxBehavior" } ] }, "type": { "description": "Business purpose of the item modifier.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierType" } ] }, "value": { "type": "string", "description": "Monetary value of the modifier as a decimal string in major/minor currency units.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "required": [ "id", "name", "tax_behavior", "type", "value" ] }, "CompactRefund": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "completed_at": { "type": "string", "description": "Date and time when the refund was finalized.", "format": "date-time" }, "employee_id": { "type": "string", "description": "ID of the employee who processed the refund.", "pattern": "^[0-9]+$" }, "lane_id": { "type": "string", "description": "ID of the checkout lane that processed the refund.", "pattern": "^[0-9]+$" }, "shopper_facing_id": { "type": "string", "description": "Human-readable refund identifier shown to the shopper." }, "started_at": { "type": "string", "description": "Date and time when the cashier started the refund.", "format": "date-time" }, "store_id": { "type": "string", "description": "ID of the store where the refund was processed.", "pattern": "^[0-9]+$" }, "subtotal": { "type": "string", "description": "Sum of line-item subtotals before promotions, discounts, and tax.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "tax_total": { "type": "string", "description": "Total tax refunded.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "total": { "type": "string", "description": "Final refund amount including tax. Refund totals are negative.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" } }, "description": "A reference to a refund of a transaction, with where and when it was rung and the amounts refunded. Retrieve the refund itself for the products returned and how the money went back.", "required": [ "id", "completed_at", "employee_id", "lane_id", "shopper_facing_id", "started_at", "store_id", "subtotal", "tax_total", "total" ] }, "CompactSetStoreVendorProduct": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9]+$" }, "alternateIdentifiers": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/DescriptionIdentifier" }, { "$ref": "#/components/schemas/BarcodeIdentifier" }, { "$ref": "#/components/schemas/ItemCodeIdentifier" } ] } }, "barcode": { "type": "string", "nullable": true }, "brandName": { "type": "string", "nullable": true }, "caseCost": { "type": "string", "minimum": 0, "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "caseSize": { "type": "number", "nullable": true }, "caseSizeDecimal": { "type": "string", "minimum": 0, "nullable": true, "deprecated": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "caseUPC": { "type": "string", "nullable": true }, "costStartTime": { "type": "string", "nullable": true, "format": "date-time" }, "description": { "type": "string" }, "eachCost": { "type": "string", "minimum": 0, "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "isOrderPrimary": { "type": "boolean" }, "isPricingEligible": { "type": "boolean" }, "itemCode": { "type": "string" }, "lbCost": { "type": "string", "minimum": 0, "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "mutationKey": { "type": "string", "format": "uuid" }, "packUPC": { "type": "string", "nullable": true }, "parentProductID": { "type": "string", "nullable": true, "pattern": "^[0-9]+$" }, "purchaseOrderUOMLock": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PurchaseOrderLineItemUnitOfMeasure" } ] }, "storeProductID": { "type": "string", "nullable": true, "pattern": "^[0-9]+$" }, "storeVendorID": { "type": "string", "pattern": "^[0-9]+$" }, "unitUPC": { "type": "string", "nullable": true }, "unitVolume": { "type": "string", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "storeVendorID" ] }, "CompactStoreProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "barcode": { "type": "string" }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "name": { "type": "string" }, "primaryVendorConfiguration": { "allOf": [ { "$ref": "#/components/schemas/PrimaryVendorConfiguration" } ] }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" } }, "required": [ "id", "barcode", "created_at", "name", "primaryVendorConfiguration", "updated_at" ] }, "CompactStoreProductImage": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the image." }, "is_primary": { "type": "boolean", "description": "Whether this is the primary display image for the product." }, "thumbnail_url": { "type": "string", "nullable": true, "description": "The thumbnail image." }, "url": { "type": "string", "description": "The full-size image." } }, "description": "A photo of a product.", "required": [ "id", "is_primary", "thumbnail_url", "url" ] }, "CompactStoreProductInventory": { "type": "object", "properties": { "current": { "type": "string", "nullable": false, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "last_changed_at": { "type": "string", "nullable": true, "format": "date-time" }, "max_stock": { "type": "string", "nullable": true }, "min_par": { "type": "string", "nullable": true } }, "required": [ "current", "last_changed_at", "max_stock", "min_par" ] }, "CompactStoreProductPar": { "type": "object", "properties": { "manual_max_stock": { "type": "string", "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "manual_reorder_point": { "type": "string", "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" } }, "required": [ "manual_max_stock", "manual_reorder_point" ] }, "CompactStoreVendor": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "code": { "type": "string", "nullable": true }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "name": { "type": "string" }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" } }, "required": [ "id", "code", "created_at", "name", "updated_at" ] }, "CompactStoreVendorProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "barcode": { "type": "string", "nullable": true }, "barcode_type": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BarcodeType" } ] }, "brand_name": { "type": "string", "nullable": true }, "case_cost": { "type": "string", "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "case_cost_start_time": { "type": "string", "nullable": true, "format": "date-time" }, "case_size": { "type": "string", "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "description": { "type": "string" }, "each_cost": { "type": "string", "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "each_cost_start_time": { "type": "string", "nullable": true, "format": "date-time" }, "is_order_primary": { "type": "boolean" }, "item_code": { "type": "string" }, "lb_cost": { "type": "string", "nullable": true, "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "lb_cost_start_time": { "type": "string", "nullable": true, "format": "date-time" }, "mutation_key": { "type": "string", "format": "uuid" }, "purchase_order_uom_lock": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PurchaseOrderLineItemUnitOfMeasure" } ] }, "store_id": { "type": "string", "nullable": true }, "store_product": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CompactStoreProduct" } ] }, "store_product_id": { "type": "string", "nullable": true }, "store_vendor": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CompactStoreVendor" } ] }, "unit_volume": { "type": "string", "nullable": true }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "id", "barcode", "barcode_type", "brand_name", "case_cost", "case_cost_start_time", "case_size", "created_at", "description", "each_cost", "each_cost_start_time", "is_order_primary", "item_code", "lb_cost", "lb_cost_start_time", "mutation_key", "purchase_order_uom_lock", "store_id", "store_product", "store_product_id", "store_vendor", "unit_volume", "updated_at", "uuid" ] }, "CompactTaxRate": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the tax rate." }, "category": { "description": "The kind of tax this rate represents.", "allOf": [ { "$ref": "#/components/schemas/TaxRateCategory" } ] }, "name": { "type": "string", "description": "Name of the tax rate, such as the jurisdiction that levies it or the category it covers." }, "value": { "type": "string", "description": "The rate charged. When `value_type` is `percentage`, this is a percentage of the taxable amount — `8.25` means 8.25%. When it is `amount`, this is a fixed amount of currency charged per unit sold.", "example": "8.25", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "value_type": { "description": "How `value` is applied: a fixed amount or a percentage.", "allOf": [ { "$ref": "#/components/schemas/TaxRateValueType" } ] } }, "required": [ "id", "category", "name", "value", "value_type" ] }, "CompactVariableWeight": { "type": "object", "properties": { "id": { "type": "string", "nullable": true, "description": "Unique identifier for the variable weight, or null when the weight was captured on a transaction without one." }, "name": { "type": "string", "description": "Human-readable name for the tare container, such as \"Produce bag\"." }, "unit": { "description": "Unit of measure the weight is expressed in, limited to the units the point of sale can weigh in.", "allOf": [ { "$ref": "#/components/schemas/VariableWeightUnit" } ] }, "value": { "type": "string", "description": "Weight of the tare container, as a decimal string in the unit of measure.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "A compact reference to a tare container weight, embedded within other resources. Where it is embedded in a completed transaction, it is the immutable reading captured at the time of sale rather than a live reference.", "required": [ "id", "name", "unit", "value" ] }, "ConflictingListParametersError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "conflicting_list_parameters" ] } }, "required": [ "error_code" ] }, "ConflictingPropertyValuesError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "conflicting_property_values" ] } }, "required": [ "error_code" ] }, "CreateDiscountRequest": { "type": "object", "properties": { "amount": { "type": "string", "description": "Discount value as a decimal string. For `amount_off`, this is in major/minor currency units (for example, \"1.25\"). For `percentage_off`, this is a whole-number percentage (`\"1.00\"` means 1%).", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "name": { "type": "string", "nullable": true, "description": "Human-readable discount name, or null when the discount is unnamed." }, "type": { "description": "How `amount` is applied: as a fixed monetary reduction or a percentage reduction.", "allOf": [ { "$ref": "#/components/schemas/DiscountType" } ] } }, "required": [ "amount", "type" ] }, "CreateEmployeeRequest": { "type": "object", "properties": { "authentication_rule": { "nullable": true, "default": null, "description": "How the employee signs in at the point of sale, or null to sign in with a PIN. Every method the rule names must have its credential set on the employee.", "allOf": [ { "$ref": "#/components/schemas/AuthenticationRule" } ] }, "badge_barcode": { "type": "string", "nullable": true, "default": null, "description": "Barcode on the badge the employee scans to sign in at the point of sale, or null for none. Unique within the banner. A deactivated employee cannot hold one unless the same request reactivates them." }, "email_address": { "type": "string", "nullable": true, "default": null, "description": "Employee's email address, or null for none. Unique within the banner.", "format": "email", "maxLength": 254 }, "first_name": { "type": "string", "description": "Employee's first name." }, "last_name": { "type": "string", "description": "Employee's last name." }, "pin": { "type": "string", "nullable": true, "default": null, "minLength": 6, "maxLength": 6, "description": "Numeric PIN the employee enters to sign in at the point of sale, or null for none. Six digits, and unique within the banner. A deactivated employee cannot hold one unless the same request reactivates them.", "pattern": "^[0-9]+$" }, "roles": { "description": "Roles the employee holds. Supplying this replaces every role the employee holds.", "maxItems": 200, "type": "array", "items": { "$ref": "#/components/schemas/UpdateEmployeeRole" } } }, "description": "Values for creating an employee.", "required": [ "first_name", "last_name" ] }, "CreateItemModifierRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable item modifier name." }, "price_tag_label": { "nullable": true, "description": "Optional shelf-tag classification for bottle deposits or container redemption value.", "allOf": [ { "$ref": "#/components/schemas/PriceTagModifier" } ] }, "store_id": { "type": "string", "description": "ID of the store the item modifier belongs to.", "pattern": "^[0-9]+$" }, "tax_behavior": { "description": "Whether the modifier is excluded from tax or inherits the product tax behavior.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierTaxBehavior" } ] }, "type": { "description": "Business purpose of the item modifier.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierType" } ] }, "value": { "type": "string", "description": "Monetary value of the modifier as a decimal string in major/minor currency units.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "required": [ "name", "store_id", "type", "value" ] }, "CreateRefundLineItem": { "type": "object", "properties": { "discount_total": { "type": "string", "description": "Discounts being reversed on this line, as a positive amount. Recorded exactly as provided. Defaults to 0.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "item_modifiers": { "maxItems": 50, "description": "Fees and deposits (bottle deposits, CRV, bag fees) returned on this line.", "type": "array", "items": { "$ref": "#/components/schemas/CreateRefundLineItemModifier" } }, "promo_savings": { "type": "string", "description": "Promotional savings being reversed on this line, as a positive amount. Recorded exactly as provided. Defaults to 0.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "quantity": { "type": "string", "description": "Number of units coming back, as a negative whole number. For items sold by weight, send -1 and provide the weight instead. Cannot return more than the line has left.", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "retail_price": { "type": "string", "description": "Price per unit — or, for items sold by weight, the price per unit of weight — the product sold at. Positive, as on the original transaction.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "return_to_inventory": { "type": "boolean", "description": "Whether the quantity coming back on this line returns to your on-hand count. Overrides the refund-level return_to_inventory. Defaults to the refund-level value, or to false when neither is provided. Acted on when the refund is first recorded, so resending the same refund ID does not revisit it." }, "tax_total": { "type": "string", "description": "Sales tax refunded on this line, as a negative amount. Defaults to 0.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "taxable_amount": { "type": "string", "description": "Portion of this line that was subject to sales tax, as a negative amount. Defaults to 0 (untaxed).", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "total": { "type": "string", "description": "Final amount refunded for this line including tax. Must equal (retail_price x quantity) — or (retail_price x weight) for items sold by weight — plus promo_savings, discount_total, the sum of fee/deposit amounts, and tax_total.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "transaction_line_item_id": { "type": "string", "description": "ID of the line on the original transaction that this line returns. Retrieve the transaction to read the IDs of its lines.", "format": "uuid" }, "weight": { "type": "string", "description": "Measured weight coming back (e.g., pounds), as a negative amount, for items sold by weight. Send quantity -1 alongside it. Cannot return more than the line has left.", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" } }, "description": "A product returned on a refund being recorded, with the quantity or weight coming back, the price it sold at, and the savings, fees, and tax being reversed with it.", "required": [ "quantity", "retail_price", "total", "transaction_line_item_id" ] }, "CreateRefundLineItemModifier": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount of this fee or deposit returned on this line, as a negative amount.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "item_modifier_id": { "type": "string", "description": "ID of the fee or deposit (e.g., bottle deposit, CRV, bag fee) as configured for your store.", "pattern": "^[0-9]+$" } }, "description": "A fee or deposit returned on a line of a refund being recorded, such as a bottle deposit, CRV, or bag fee.", "required": [ "amount", "item_modifier_id" ] }, "CreateRefundPayment": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount returned to this payment method, as a negative amount. Cannot return more than the payment has left.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "completed_at": { "type": "string", "description": "When the refund settled. Defaults to the refund's completed_at.", "format": "date-time" }, "external_transaction_id": { "type": "string", "maxLength": 250, "description": "Your payment processor's reference for the refund. Surrounding whitespace is removed; the value is otherwise stored as provided so your systems can look it up later, and it is never interpreted." }, "transaction_payment_id": { "type": "string", "description": "ID of the payment on the original transaction that this returns money to. How it was tendered is taken from that payment.", "format": "uuid" } }, "description": "Money returned on one of the payments the original transaction collected.", "required": [ "amount", "external_transaction_id", "transaction_payment_id" ] }, "CreateRefundRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique refund ID generated by your system (UUIDv7). It serves as the idempotency key for the request: sending the same refund twice with the same ID returns the refund already recorded rather than creating a duplicate. Generate it before your first attempt and reuse it on every retry. Sending different values under an ID already used is rejected.", "format": "uuid" }, "completed_at": { "type": "string", "description": "When the refund was completed in your system.", "format": "date-time" }, "employee_id": { "type": "string", "nullable": true, "description": "ID of the employee to record this refund under. Defaults to the employee Vori maintains for transactions submitted through this API.", "pattern": "^[0-9]+$" }, "external_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "Your own identifier for this refund, such as a return number from your e-commerce platform. Surrounding whitespace is removed; the value is otherwise stored as provided and never interpreted, and you can filter transactions by it. Vori does not require it to be unique." }, "lane_id": { "type": "string", "nullable": true, "description": "ID of the lane to record this refund under. Defaults to the lane Vori maintains for transactions submitted through this API.", "pattern": "^[0-9]+$" }, "line_items": { "minItems": 1, "maxItems": 2500, "description": "Products coming back on the refund.", "type": "array", "items": { "$ref": "#/components/schemas/CreateRefundLineItem" } }, "metadata": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 }, "example": { "order_source": "shopify", "fulfillment_id": "88213" }, "nullable": true, "description": "Your own key/value pairs, stored with the refund and returned unchanged. Vori never interprets them. Up to 50 keys; key names up to 40 characters of letters, numbers, underscores, and hyphens; values up to 500 characters. Keys beginning with \"vori\" are reserved. Do not put personal or sensitive information here — these values flow into reporting and data exports." }, "payments": { "minItems": 1, "maxItems": 50, "description": "Payments the refund returns money to.", "type": "array", "items": { "$ref": "#/components/schemas/CreateRefundPayment" } }, "return_to_inventory": { "type": "boolean", "description": "Whether the products coming back return to your on-hand counts. Applies to every line that does not answer for itself; a line providing its own return_to_inventory overrides it. Defaults to false. Acted on when the refund is first recorded, so resending the same refund ID does not revisit it." }, "tax_total": { "type": "string", "description": "Total sales tax refunded, as a negative amount. Must equal the sum of the line-item tax totals.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "total": { "type": "string", "description": "Final refund total including tax, as a negative amount. Must equal the sum of the line totals, and the payments must add up to this amount.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" } }, "description": "A refund your own system processed against a transaction Vori already recorded, with the products coming back and the money going out.", "required": [ "id", "completed_at", "line_items", "payments", "tax_total", "total" ] }, "CreateShopperRequest": { "type": "object", "properties": { "email_address": { "type": "string", "nullable": true, "description": "Email address on file for the shopper.", "format": "email", "maxLength": 254 }, "enrolled_in_loyalty_program": { "type": "boolean", "default": false, "description": "Whether the shopper is enrolled in the loyalty program. Shoppers must explicitly opt into the loyalty program, typically at the POS. Digital gift card recipients are also stored as shoppers, but are only opted into the loyalty program after giving explicit permission." }, "first_name": { "type": "string", "nullable": true, "description": "Given name of the shopper." }, "last_name": { "type": "string", "nullable": true, "description": "Family name of the shopper." }, "phone_number": { "type": "string", "description": "Phone number on file for the shopper, and what a loyalty member gives at checkout to be identified.", "format": "phone", "pattern": "^\\+[1-9]\\d{1,14}$" }, "postal_code": { "type": "string", "nullable": true, "description": "Postal code on file for the shopper." } }, "required": [ "phone_number" ] }, "CreateStoreDepartmentRequest": { "type": "object", "properties": { "exclude_from_sales_reporting": { "type": "boolean", "description": "Whether sales from this department are omitted from sales reporting. Defaults to false." }, "name": { "type": "string", "description": "Human-readable department name." }, "parent_department_id": { "type": "string", "nullable": true, "description": "ID of the parent department, or null for a top-level department. A parent must itself be top-level: departments nest one level deep.", "pattern": "^[0-9]+$" }, "store_id": { "type": "string", "description": "The store the department belongs to.", "pattern": "^[0-9]+$" } }, "required": [ "name", "store_id" ] }, "CreateStoreProduct": { "type": "object", "properties": { "active": { "type": "boolean", "default": true }, "alcohol_by_volume": { "type": "string", "nullable": true, "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "barcode": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "case_size": { "type": "integer", "nullable": true }, "country_of_origin": { "type": "string", "nullable": true, "maxLength": 3, "minLength": 3 }, "department_id": { "type": "string", "pattern": "^-?[0-9]+$" }, "description": { "type": "string", "nullable": true }, "disable_barcode_sanitization": { "type": "boolean", "description": "When true, the barcode is stored verbatim and the product's `barcode_type` is set to `Unsanitized`. When false, an existing `Unsanitized` product is re-sanitized on save. When omitted, the existing `barcode_type` is preserved (partial updates are safe)." }, "discount_restrictions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/DiscountRestriction" } }, "ebt_enabled": { "type": "boolean", "default": false }, "ecommerce_enabled": { "type": "boolean", "default": false }, "food_modifier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "ingredients": { "type": "string", "nullable": true }, "inventory_change": { "$ref": "#/components/schemas/InitialStoreProductInventory" }, "is_blackhawk_gift_card": { "type": "boolean", "default": false }, "is_reloadable_blackhawk_gift_card": { "type": "boolean", "default": false }, "is_tippable": { "type": "boolean", "default": false }, "item_modifier_ids": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+$" } }, "last_printed_at": { "type": "string", "nullable": true, "format": "date-time" }, "loyalty_points_per_dollar": { "type": "string", "nullable": true, "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "manual_item": { "type": "boolean", "default": false }, "maximum_retail_price": { "type": "string", "nullable": true, "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "min_customer_age": { "type": "integer" }, "minimum_retail_price": { "type": "string", "nullable": true, "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "name": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "pack_size": { "type": "integer", "nullable": true }, "par": { "$ref": "#/components/schemas/CompactStoreProductPar" }, "primary_vendor_configuration": { "allOf": [ { "$ref": "#/components/schemas/PrimaryVendorConfiguration" } ] }, "print_physical_tag": { "type": "boolean", "default": false }, "prompt_for_quantity": { "type": "boolean", "default": false }, "retail_price": { "type": "string", "nullable": true, "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "retail_price_input_method": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoreProductPriceInputMethod" } ] }, "retail_price_source": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoreProductPriceSource" } ] }, "retail_price_source_platform": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoreProductPriceSourcePlatform" } ] }, "retail_price_unit_of_measure_id": { "type": "string", "nullable": true, "pattern": "^-?[0-9]+$" }, "shelf_life_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 999, "description": "Shelf life in days sent to deli scales (Hobart, eplum, Ishida); the scale computes the sell-by date from it. 1-999, or null for no Vori-managed shelf life." }, "snap_incentive_earnable": { "type": "boolean", "default": false }, "snap_incentive_redeemable": { "type": "boolean", "default": false }, "sold_by_weight": { "type": "boolean", "default": false }, "store_product_group_rule_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "store_vendor_products": { "type": "array", "items": { "$ref": "#/components/schemas/CompactSetStoreVendorProduct" } }, "sync_to_deli_scales": { "type": "boolean", "default": false }, "target_margin": { "type": "number", "nullable": true }, "tax_rate_ids": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+$" } }, "unit_volume_quantity": { "type": "string", "nullable": true, "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "unit_volume_uom_name": { "type": "string", "nullable": true }, "variable_sale_price": { "type": "boolean", "default": false }, "variable_weight_ids": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+$" } }, "wic_enabled": { "type": "boolean", "default": false }, "wic_override_plu": { "type": "string", "nullable": true } }, "required": [ "barcode", "department_id", "name" ] }, "CreateStoreProductRequest": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateStoreProduct" } }, "required": [ "data" ] }, "CreateTaxRateRequest": { "type": "object", "properties": { "active": { "type": "boolean", "default": true, "description": "Whether the rate is charged at checkout. An inactive rate stays configured but is not applied." }, "category": { "description": "The kind of tax this rate represents.", "allOf": [ { "$ref": "#/components/schemas/TaxRateCategory" } ] }, "name": { "type": "string", "description": "Name of the tax rate, such as the jurisdiction that levies it or the category it covers." }, "value": { "type": "string", "description": "The rate charged. When `value_type` is `percentage`, this is a percentage of the taxable amount — `8.25` means 8.25%. When it is `amount`, this is a fixed amount of currency charged per unit sold.", "example": "8.25", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "value_type": { "description": "How `value` is applied: a fixed amount or a percentage.", "allOf": [ { "$ref": "#/components/schemas/TaxRateValueType" } ] } }, "required": [ "category", "name", "value", "value_type" ] }, "CreateTransactionCardBrand": { "type": "string", "enum": [ "american_express", "china_union_pay", "debit", "diners_club", "discover", "jcb", "mastercard", "visa" ] }, "CreateTransactionLineItem": { "type": "object", "properties": { "discount_total": { "type": "string", "description": "Total discounts applied to this line, as a negative amount. Recorded exactly as provided. Defaults to 0.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "item_modifiers": { "maxItems": 50, "description": "Fees and deposits (bottle deposits, CRV, bag fees) charged on this line.", "type": "array", "items": { "$ref": "#/components/schemas/CreateTransactionLineItemModifier" } }, "promo_savings": { "type": "string", "description": "Total promotional savings applied to this line, as a negative amount. Recorded exactly as provided. Defaults to 0.", "format": "negative-monetary", "pattern": "^(-[0-9]+(\\.[0-9]+)?|0+(\\.0+)?)$", "example": "-199.99" }, "quantity": { "type": "string", "description": "Number of units sold, as a whole number. For items sold by weight, send 1 and provide the weight instead.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "retail_price": { "type": "string", "description": "Price per unit — or, for items sold by weight, the price per unit of weight (e.g., per pound) — before any savings or tax.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "store_product_id": { "type": "string", "description": "ID of the product in your store's catalog.", "pattern": "^[0-9]+$" }, "tax_total": { "type": "string", "description": "Sales tax charged on this line. Defaults to 0.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "taxable_amount": { "type": "string", "description": "Portion of this line that is subject to sales tax. Defaults to 0 (untaxed).", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "total": { "type": "string", "description": "Final amount for this line including tax. Must equal (retail_price x quantity) — or (retail_price x weight) for items sold by weight — plus promo_savings, discount_total, the sum of fee/deposit amounts, and tax_total.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "weight": { "type": "string", "description": "Measured weight (e.g., pounds), for items sold by weight. When the item is priced by weight, send quantity 1; retail_price is the price per unit of weight, and the line total is based on retail_price x weight.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "A product sold on a transaction being recorded, with its quantity or weight, price, savings, fees, and tax.", "required": [ "quantity", "retail_price", "store_product_id", "total" ] }, "CreateTransactionLineItemModifier": { "type": "object", "properties": { "amount": { "type": "string", "description": "Total amount charged for this fee or deposit on this line.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "item_modifier_id": { "type": "string", "description": "ID of the fee or deposit (e.g., bottle deposit, CRV, bag fee) as configured for your store.", "pattern": "^[0-9]+$" } }, "description": "A fee or deposit — such as a bottle deposit, CRV, or bag fee — charged on a line of a transaction being recorded.", "required": [ "amount", "item_modifier_id" ] }, "CreateTransactionPayment": { "type": "object", "properties": { "account_number_last4": { "type": "string", "minLength": 4, "maxLength": 4, "description": "Last 4 digits of the card number, if paid by card.", "pattern": "^[0-9]+$" }, "amount": { "type": "string", "description": "Amount collected with this payment method.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "card_brand": { "description": "Card brand, if paid by card. Shown on receipts and in reporting.", "allOf": [ { "$ref": "#/components/schemas/CreateTransactionCardBrand" } ] }, "completed_at": { "type": "string", "description": "When the payment settled. Defaults to the transaction's completed_at.", "format": "date-time" }, "external_transaction_id": { "type": "string", "maxLength": 250, "description": "Your payment processor's transaction reference. Stored exactly as provided so your systems can look it up later; it is never interpreted." }, "payment_type": { "description": "How the transaction was paid.", "allOf": [ { "$ref": "#/components/schemas/CreateTransactionPaymentType" } ] } }, "description": "A payment collected on a transaction being recorded, including how it was tendered, the amount, and the processor reference.", "required": [ "amount", "external_transaction_id", "payment_type" ] }, "CreateTransactionPaymentType": { "type": "string", "enum": [ "check", "credit", "debit" ] }, "CreateTransactionRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique transaction ID generated by your system (UUIDv7). It serves as the idempotency key for the request: sending the same transaction twice with the same ID returns the transaction already recorded rather than creating a duplicate. Generate it before your first attempt and reuse it on every retry. Sending different values under an ID already used is rejected.", "format": "uuid" }, "completed_at": { "type": "string", "description": "When the transaction was completed in your system.", "format": "date-time" }, "employee_id": { "type": "string", "nullable": true, "description": "ID of the employee to record this transaction under. Defaults to the employee Vori maintains for transactions submitted through this API.", "pattern": "^[0-9]+$" }, "external_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "Your own identifier for this transaction, such as an order number from your e-commerce platform. Stored exactly as provided and never interpreted, and you can filter transactions by it. Vori does not require it to be unique." }, "lane_id": { "type": "string", "nullable": true, "description": "ID of the lane to record this transaction under. Defaults to the lane Vori maintains for transactions submitted through this API.", "pattern": "^[0-9]+$" }, "line_items": { "minItems": 1, "maxItems": 2500, "description": "Products on the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/CreateTransactionLineItem" } }, "metadata": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 }, "example": { "order_source": "shopify", "fulfillment_id": "88213" }, "nullable": true, "description": "Your own key/value pairs, stored with the transaction and returned unchanged. Vori never interprets them. Up to 50 keys; key names up to 40 characters of letters, numbers, underscores, and hyphens; values up to 500 characters. Keys beginning with \"vori\" are reserved. Do not put personal or sensitive information here — these values flow into reporting and data exports." }, "payments": { "minItems": 1, "maxItems": 50, "description": "Payments applied to the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/CreateTransactionPayment" } }, "shopper_id": { "type": "string", "description": "ID of the loyalty shopper who placed the transaction, if known. Links the transaction to their loyalty account.", "format": "uuid" }, "store_id": { "type": "string", "description": "ID of the store where the transaction took place.", "pattern": "^[0-9]+$" }, "tax_total": { "type": "string", "description": "Total sales tax charged on the transaction. Must equal the sum of the line-item tax totals.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "total": { "type": "string", "description": "Final transaction total including tax. Must equal the sum of the line totals, and the payments must add up to this amount.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "A completed checkout to record against a store, with its products, payments, and totals.", "required": [ "id", "completed_at", "line_items", "payments", "store_id", "tax_total", "total" ] }, "CreateVariableWeightRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name for the tare container, such as \"Produce bag\"." }, "store_id": { "type": "string", "description": "ID of the store the variable weight belongs to. Variable weights are not shared between stores.", "pattern": "^[0-9]+$" }, "unit_of_measure": { "description": "Unit of measure the weight is expressed in, limited to the units the point of sale can weigh in.", "allOf": [ { "$ref": "#/components/schemas/VariableWeightUnit" } ] }, "value": { "type": "string", "description": "Weight of the tare container, as a decimal string in the unit of measure.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "required": [ "name", "store_id", "value" ] }, "DeactivatedEmployeeCredentialsError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "deactivated_employee_credentials" ] } }, "required": [ "error_code" ] }, "DepartmentHasActiveProductsError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "department_has_active_products" ] } }, "required": [ "error_code" ] }, "DepartmentHasActiveSubDepartmentsError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "department_has_active_sub_departments" ] } }, "required": [ "error_code" ] }, "DescriptionIdentifier": { "type": "object", "properties": { "description": { "type": "string" }, "type": { "allOf": [ { "$ref": "#/components/schemas/StoreVendorProductIdentifierType" } ] } }, "required": [ "description", "type" ] }, "Discount": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "amount": { "type": "string", "description": "Discount value as a decimal string. For `amount_off`, this is in major/minor currency units (for example, \"1.25\"). For `percentage_off`, this is a whole-number percentage (`\"1.00\"` means 1%).", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "name": { "type": "string", "nullable": true, "description": "Human-readable discount name, or null when the discount is unnamed." }, "type": { "description": "How `amount` is applied: as a fixed monetary reduction or a percentage reduction.", "allOf": [ { "$ref": "#/components/schemas/DiscountType" } ] }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" } }, "description": "A fixed or percentage reduction a cashier can apply to an order at the register.", "required": [ "id", "amount", "created_at", "name", "type", "updated_at" ] }, "DiscountList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Discount" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "description": "A page of discounts.", "required": [ "data", "has_more" ] }, "DiscountRestriction": { "type": "string", "enum": [ "NO_DISCOUNT_WHEN_ON_PROMOTION", "NO_DISCOUNTING", "NO_DOUBLE_DISCOUNTING" ] }, "DiscountType": { "type": "string", "enum": [ "amount_off", "percentage_off" ] }, "DuplicateBarcodeDetail": { "type": "object", "properties": { "barcode": { "type": "string" }, "barcode_type": { "allOf": [ { "$ref": "#/components/schemas/BarcodeType" } ] }, "store_product_id": { "type": "string" } }, "required": [ "barcode", "barcode_type", "store_product_id" ] }, "DuplicateBarcodeTypesForProductError": { "type": "object", "properties": { "duplicates": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateBarcodeDetail" } }, "error_code": { "type": "string", "enum": [ "duplicate_barcode_types_for_product" ] } }, "required": [ "duplicates", "error_code" ] }, "DuplicateBarcodesError": { "type": "object", "properties": { "duplicates": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicateBarcodeDetail" } }, "error_code": { "type": "string", "enum": [ "duplicate_barcodes" ] } }, "required": [ "duplicates", "error_code" ] }, "EmailAddressAlreadyAssignedError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "email_address_already_assigned" ] } }, "required": [ "error_code" ] }, "Employee": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "authentication_rule": { "nullable": true, "description": "Effective rule that determines how the employee authenticates at the POS.", "allOf": [ { "$ref": "#/components/schemas/AuthenticationRule" } ] }, "badge_barcode": { "type": "string", "nullable": true, "description": "Barcode on the badge the employee scans to sign in at the point of sale, or null when none is configured. Returned only when requested with `include=badge_barcode` by a caller holding the `employees:read_credentials` permission, and absent from the response otherwise." }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "deactivated_at": { "type": "string", "nullable": true, "description": "When the employee was deactivated, or null when the employee is active.", "format": "date-time" }, "editable": { "type": "boolean", "description": "Whether the employee can be changed. Employees Vori creates and manages are not editable." }, "email_address": { "type": "string", "nullable": true, "description": "Employee's email address, or null when none is configured.", "format": "email", "maxLength": 254 }, "first_name": { "type": "string", "description": "Employee's first name." }, "last_name": { "type": "string", "description": "Employee's last name." }, "pin": { "type": "string", "nullable": true, "minLength": 6, "maxLength": 6, "description": "Numeric PIN used by the employee for POS authentication, or null when none is configured. Returned only when requested with `include=pin` by a caller holding the `employees:read_credentials` permission, and absent from the response otherwise.", "pattern": "^[0-9]+$" }, "roles": { "description": "Roles assigned to the employee.", "type": "array", "items": { "$ref": "#/components/schemas/EmployeeRole" } }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" }, "virtual": { "type": "boolean", "description": "Whether the employee exists only to attribute orders and cannot sign in at a terminal." } }, "description": "A staff member at a store, to whom point-of-sale activity can be attributed.", "required": [ "id", "authentication_rule", "created_at", "deactivated_at", "editable", "email_address", "first_name", "last_name", "roles", "updated_at", "virtual" ] }, "EmployeeCredential": { "type": "string", "enum": [ "badge_barcode", "pin" ] }, "EmployeeList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Employee" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "description": "A page of employees.", "required": [ "data", "has_more" ] }, "EmployeeNotUserEditableError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "employee_not_user_editable" ] } }, "required": [ "error_code" ] }, "EmployeeRole": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the role that is held." }, "name": { "description": "Name of the role.", "allOf": [ { "$ref": "#/components/schemas/RoleName" } ] }, "store_id": { "type": "string", "nullable": true, "description": "The store the role applies at, or null when it applies at every store in the banner." } }, "description": "A role held by an employee, and the store it applies at. The same role can be held at more than one store.", "required": [ "id", "name", "store_id" ] }, "FoodModifier": { "type": "object", "properties": { "id": { "type": "string" }, "item_modifier": { "description": "Item modifier data", "allOf": [ { "$ref": "#/components/schemas/FoodModifierItemModifier" } ] }, "priority": { "type": "integer", "description": "Display priority (lower = shown first)" } }, "required": [ "id", "item_modifier", "priority" ] }, "FoodModifierItemModifier": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Display name for the modifier option" }, "value": { "type": "string", "description": "Price adjustment for this modifier", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "required": [ "id", "name", "value" ] }, "InitialStoreProductInventory": { "type": "object", "properties": { "completed_at": { "type": "string", "nullable": true, "deprecated": true, "format": "date-time" }, "count": { "type": "string", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "source_type": { "allOf": [ { "$ref": "#/components/schemas/InventoryChangeSourceType" } ] } }, "required": [ "count", "source_type" ] }, "InsufficientPermissionsError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "insufficient_permissions" ] }, "error_details": { "$ref": "#/components/schemas/InsufficientPermissionsErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "InsufficientPermissionsErrorDetails": { "type": "object", "properties": { "action": { "allOf": [ { "$ref": "#/components/schemas/Action" } ] }, "resource": { "allOf": [ { "$ref": "#/components/schemas/Resource" } ] } }, "required": [ "action", "resource" ] }, "InvalidAuthenticationRuleError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_authentication_rule" ] } }, "required": [ "error_code" ] }, "InvalidBarcodeError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_barcode" ] } }, "required": [ "error_code" ] }, "InvalidDepartmentError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_department" ] } }, "required": [ "error_code" ] }, "InvalidDepartmentHierarchyError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_department_hierarchy" ] } }, "required": [ "error_code" ] }, "InvalidEmployeeRoleError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_employee_role" ] } }, "required": [ "error_code" ] }, "InvalidFoodModifiersError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_food_modifiers" ] } }, "required": [ "error_code" ] }, "InvalidItemModifiersError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_item_modifiers" ] } }, "required": [ "error_code" ] }, "InvalidListCursorError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_list_cursor" ] } }, "required": [ "error_code" ] }, "InvalidParentDepartmentError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_parent_department" ] } }, "required": [ "error_code" ] }, "InvalidStoreError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_store" ] } }, "required": [ "error_code" ] }, "InvalidStoreProductsError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_store_products" ] } }, "required": [ "error_code" ] }, "InvalidStoresError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_stores" ] } }, "required": [ "error_code" ] }, "InvalidTaxRatesError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_tax_rates" ] } }, "required": [ "error_code" ] }, "InvalidUnitOfMeasureError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_unit_of_measure" ] } }, "required": [ "error_code" ] }, "InvalidVariableWeightsError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "invalid_variable_weights" ] } }, "required": [ "error_code" ] }, "InventoryChangeSourceType": { "type": "string", "enum": [ "API", "CLEAR_ON_ORDER", "DASH_PRODUCT_DETAILS", "DASHBOARD_INVENTORY_PAGE", "HANDHELD_INVENTORY_COUNT", "HANDHELD_INVENTORY_MANUAL", "HANDHELD_INVENTORY_RESTOCK", "HANDHELD_INVENTORY_SHRINK", "HANDHELD_ORDERING_COUNT", "HANDHELD_PRODUCT_MANUAL", "INVENTORY_RECOUNT", "INVENTORY_UPLOAD", "INVOICE_SHIPPED_QTY", "ONBOARDING_APL_IMPORT", "POS_REFUND", "POS_SALE", "PURCHASE_ORDER", "RDS_IMPORT", "STORE_TRANSFER" ] }, "InventoryUpdate": { "type": "object", "properties": { "reason_description": { "type": "string", "nullable": true, "description": "A note explaining the change." }, "reason_type": { "description": "Why the quantity changed.", "allOf": [ { "$ref": "#/components/schemas/InventoryUpdateReasonType" } ] }, "type": { "description": "Whether the value replaces (`set`) the on-hand quantity or moves (`adjustment`) it by that amount.", "allOf": [ { "$ref": "#/components/schemas/InventoryUpdateType" } ] }, "value": { "type": "string", "description": "The quantity to set the on-hand to, or by which to adjust it. Negative values reduce it.", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" } }, "description": "A change to a product's on-hand quantity.", "required": [ "type", "value" ] }, "InventoryUpdateReasonType": { "type": "string", "enum": [ "shrink_damage", "shrink_donation", "shrink_other", "shrink_spoilage", "shrink_theft" ] }, "InventoryUpdateType": { "type": "string", "enum": [ "adjustment", "set" ] }, "ItemCodeIdentifier": { "type": "object", "properties": { "item_code": { "type": "string" }, "type": { "allOf": [ { "$ref": "#/components/schemas/StoreVendorProductIdentifierType" } ] } }, "required": [ "item_code", "type" ] }, "ItemModifier": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "name": { "type": "string", "description": "Human-readable item modifier name." }, "price_tag_label": { "nullable": true, "description": "Optional shelf-tag classification for bottle deposits or container redemption value.", "allOf": [ { "$ref": "#/components/schemas/PriceTagModifier" } ] }, "store_id": { "type": "string", "description": "ID of the store the item modifier belongs to.", "pattern": "^[0-9]+$" }, "tax_behavior": { "description": "Whether the modifier is excluded from tax or inherits the product tax behavior.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierTaxBehavior" } ] }, "type": { "description": "Business purpose of the item modifier.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierType" } ] }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" }, "value": { "type": "string", "description": "Monetary value of the modifier as a decimal string in major/minor currency units.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "A charge added alongside a product's price, such as a bottle deposit.", "required": [ "id", "created_at", "name", "price_tag_label", "store_id", "tax_behavior", "type", "updated_at", "value" ] }, "ItemModifierInUseError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "item_modifier_in_use" ] } }, "required": [ "error_code" ] }, "ItemModifierList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ItemModifier" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "required": [ "data", "has_more" ] }, "ItemModifierTaxBehavior": { "type": "string", "enum": [ "EXCLUDE", "INHERIT_FROM_STORE_PRODUCT" ] }, "ItemModifierType": { "type": "string", "enum": [ "bottle_deposit", "custom", "food_modifier" ] }, "Lane": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "editable": { "type": "boolean", "description": "Whether the lane can be changed. Lanes Vori creates and manages are not editable." }, "name": { "type": "string", "nullable": true, "description": "Human-readable lane name." }, "order_id_prefix": { "type": "string", "description": "Prefix added to shopper-facing order identifiers created by this lane." }, "store_id": { "type": "string", "description": "ID of the store where the lane is located.", "pattern": "^[0-9]+$" }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" }, "virtual": { "type": "boolean", "description": "Whether the lane exists only to attribute orders and has no physical terminal." } }, "description": "A checkout lane within a store, carrying the name it is known by and the prefix it applies to shopper-facing order identifiers.", "required": [ "id", "created_at", "editable", "name", "order_id_prefix", "store_id", "updated_at", "virtual" ] }, "LaneList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lane" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "required": [ "data", "has_more" ] }, "MissingCredentialsForAuthenticationRuleError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "missing_credentials_for_authentication_rule" ] } }, "required": [ "error_code" ] }, "MissingStoreError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "missing_store" ] } }, "required": [ "error_code" ] }, "MissingStoreProductSelectionError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "missing_store_product_selection" ] } }, "required": [ "error_code" ] }, "MultipleBannersSelectedError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "multiple_banners_selected" ] } }, "required": [ "error_code" ] }, "NoBannerAssociationError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "no_banner_association" ] } }, "required": [ "error_code" ] }, "PinAlreadyAssignedError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "pin_already_assigned" ] } }, "required": [ "error_code" ] }, "PriceTagModifier": { "type": "string", "enum": [ "BOTTLE_DEPOSIT", "CRV" ] }, "PrimaryVendorConfiguration": { "type": "string", "enum": [ "LATEST_COST", "SELECTED_BY_USER" ] }, "PurchaseOrderLineItemUnitOfMeasure": { "type": "string", "enum": [ "CASE", "EACH", "LB" ] }, "ReceiptType": { "type": "string", "enum": [ "email", "print", "sms" ] }, "RefundExceedsField": { "type": "string", "enum": [ "line_discount_total", "line_item_modifier_total", "line_promo_savings", "line_quantity", "line_tax_total", "line_taxable_amount", "line_total", "line_weight", "payment_amount" ] }, "RefundExceedsOriginalError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "refund_exceeds_original" ] }, "error_details": { "$ref": "#/components/schemas/RefundExceedsOriginalErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "RefundExceedsOriginalErrorDetails": { "type": "object", "properties": { "field": { "allOf": [ { "$ref": "#/components/schemas/RefundExceedsField" } ] }, "remaining": { "type": "string" }, "requested": { "type": "string" }, "transaction_line_item_id": { "type": "string", "format": "uuid" }, "transaction_payment_id": { "type": "string", "format": "uuid" } }, "required": [ "field", "remaining", "requested" ] }, "RefundLineItemsNotFoundError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "refund_line_items_not_found" ] }, "error_details": { "$ref": "#/components/schemas/RefundLineItemsNotFoundErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "RefundLineItemsNotFoundErrorDetails": { "type": "object", "properties": { "transaction_line_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "transaction_line_item_ids" ] }, "RefundNotRefundableReason": { "type": "string", "enum": [ "not_a_sale", "not_api_originated", "not_completed" ] }, "RefundPaymentsNotFoundError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "refund_payments_not_found" ] }, "error_details": { "$ref": "#/components/schemas/RefundPaymentsNotFoundErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "RefundPaymentsNotFoundErrorDetails": { "type": "object", "properties": { "transaction_payment_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "transaction_payment_ids" ] }, "RefundTransactionNotRefundableError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "refund_transaction_not_refundable" ] }, "error_details": { "$ref": "#/components/schemas/RefundTransactionNotRefundableErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "RefundTransactionNotRefundableErrorDetails": { "type": "object", "properties": { "reason": { "allOf": [ { "$ref": "#/components/schemas/RefundNotRefundableReason" } ] }, "transaction_id": { "type": "string", "format": "uuid" } }, "required": [ "reason", "transaction_id" ] }, "Resource": { "type": "string", "enum": [ "*", "accounting_integration", "agent_chats", "api_clients", "asynchronous_tasks", "banners", "blackhawk_transactions", "capabilities", "coupons", "custom_quick_actions", "datacap_transactions", "departments", "discounts", "ditto_auth_tokens", "edge_agents", "electronic_shelf_labels", "employees", "feature_orientations", "files", "food_modifiers", "gift_cards", "gl_code_mappings", "house_accounts", "inventory", "inventory_sessions", "inventory_settings", "invoices", "item_modifiers", "label_dimension_sets", "label_sheet_profiles", "label_stock_products", "lanes", "loyalty_bonuses", "loyalty_campaigns", "loyalty_rewards", "notification_templates", "offers", "order_guides", "pos_banner_configurations", "pos_orders", "pos_tills", "price_tags", "product_ranges", "products", "promotions", "purchase_orders", "receiving", "reporting", "revision_sessions", "revisions", "roles", "shopper_tags", "shoppers", "store_product_inventory_counts", "store_product_lots", "store_product_rules", "store_product_tag_templates", "store_snap_incentive_program_coupons", "store_vendor_merge_requests", "store_vendor_product_merge_requests", "store_vendor_products", "store_vendors", "stores", "tag_printings", "tag_template_presets", "tag_templates", "tax_rates", "users", "variable_weights", "vendor_merge_requests", "vendor_product_merge_requests", "vendors", "wallet_payments", "wic_products" ] }, "RoleName": { "type": "string", "enum": [ "everyone", "manager" ] }, "Shopper": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "email_address": { "type": "string", "nullable": true, "description": "Email address on file for the shopper.", "format": "email", "maxLength": 254 }, "email_validated": { "type": "boolean", "description": "Whether the shopper has confirmed their email address." }, "enrolled_in_loyalty_program": { "type": "boolean", "description": "Whether the shopper is enrolled in the loyalty program. Shoppers must explicitly opt into the loyalty program, typically at the POS. Digital gift card recipients are also stored as shoppers, but are only opted into the loyalty program after giving explicit permission." }, "first_name": { "type": "string", "nullable": true, "description": "Given name of the shopper." }, "joined_at_store_id": { "type": "string", "nullable": true, "description": "ID of the store where the shopper enrolled.", "pattern": "^[0-9]+$" }, "last_name": { "type": "string", "nullable": true, "description": "Family name of the shopper." }, "phone_number": { "type": "string", "description": "Phone number on file for the shopper, and what a loyalty member gives at checkout to be identified.", "format": "phone", "pattern": "^\\+[1-9]\\d{1,14}$" }, "point_balance": { "type": "string", "description": "Loyalty points currently available to the shopper.", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "postal_code": { "type": "string", "nullable": true, "description": "Postal code on file for the shopper." }, "subscribed_to_email": { "type": "boolean", "description": "Whether the shopper has opted in to marketing emails." }, "subscribed_to_sms": { "type": "boolean", "description": "Whether the shopper has opted in to marketing text messages." }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" } }, "description": "A person a store can recognize at checkout, whether as a loyalty member or as the holder of a gift card. A shopper belongs to the banner rather than to any one store.", "required": [ "id", "created_at", "email_address", "email_validated", "enrolled_in_loyalty_program", "first_name", "joined_at_store_id", "last_name", "phone_number", "point_balance", "postal_code", "subscribed_to_email", "subscribed_to_sms", "updated_at" ] }, "ShopperList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shopper" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "required": [ "data", "has_more" ] }, "Store": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the store." }, "address": { "type": "string", "nullable": true, "description": "Formatted street address for the store." }, "name": { "type": "string", "description": "Human-readable store name." }, "supports_wic": { "type": "boolean", "description": "Whether the store accepts WIC as a payment method." } }, "description": "A physical store location operating under a banner.", "required": [ "id", "address", "name", "supports_wic" ] }, "StoreDepartment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the store department." }, "deactivated_at": { "type": "string", "nullable": true, "description": "When the department was deactivated, or null when it is active.", "format": "date-time" }, "exclude_from_sales_reporting": { "type": "boolean", "description": "Whether sales from this department are omitted from sales reporting." }, "name": { "type": "string", "description": "Human-readable department name." }, "parent_department_id": { "type": "string", "nullable": true, "description": "ID of the parent department, or null for a top-level department." } }, "description": "A grouping of products within a store, optionally nested under a parent department.", "required": [ "id", "deactivated_at", "exclude_from_sales_reporting", "name", "parent_department_id" ] }, "StoreDepartmentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreDepartment" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "description": "A page of departments.", "required": [ "data", "has_more" ] }, "StoreList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "required": [ "data", "has_more" ] }, "StoreProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "active": { "type": "boolean", "description": "Whether the product is active." }, "active_vendor": { "description": "The vendor currently supplying this product.", "allOf": [ { "$ref": "#/components/schemas/CompactStoreVendor" } ] }, "active_vendor_product": { "description": "The vendor catalog entry currently supplying this product.", "allOf": [ { "$ref": "#/components/schemas/CompactStoreVendorProduct" } ] }, "barcode": { "type": "string", "description": "Primary barcode." }, "brand": { "type": "string", "nullable": true, "description": "Brand name." }, "country_of_origin": { "type": "string", "nullable": true, "maxLength": 3, "minLength": 3, "description": "ISO 3166-1 alpha-3 country code of origin." }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "department_id": { "type": "string", "description": "ID of the store department this product belongs to.", "pattern": "^[0-9]+$" }, "description": { "type": "string", "nullable": true, "description": "Short description, intended for character-limited use cases (e.g., printed receipts)." }, "ebt_enabled": { "type": "boolean", "description": "Whether the product is eligible for EBT/SNAP payment." }, "ecommerce_enabled": { "type": "boolean", "description": "Whether the product is available for e-commerce." }, "food_modifier_categories": { "description": "Food modifier categories, and their modifiers, available for this product, ordered by category priority.", "type": "array", "items": { "$ref": "#/components/schemas/CompactFoodModifierCategory" } }, "images": { "description": "Photos of this product.", "type": "array", "items": { "$ref": "#/components/schemas/CompactStoreProductImage" } }, "inventory": { "description": "Current inventory levels. Included when requested via `include=inventory`.", "allOf": [ { "$ref": "#/components/schemas/CompactStoreProductInventory" } ] }, "is_blackhawk_gift_card": { "type": "boolean", "description": "Whether the product is a Blackhawk gift card." }, "is_reloadable_blackhawk_gift_card": { "type": "boolean", "description": "Whether the product is a reloadable Blackhawk gift card." }, "is_tippable": { "type": "boolean", "description": "Whether purchases of this product can include a tip." }, "item_modifiers": { "description": "Item modifiers available for this product.", "type": "array", "items": { "$ref": "#/components/schemas/CompactItemModifier" } }, "loyalty_points_per_dollar": { "type": "string", "nullable": true, "description": "Loyalty points earned per dollar spent. Null defaults to one point per dollar.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "manual_item": { "type": "boolean", "description": "Whether the product is entered manually at the register rather than scanned." }, "maximum_retail_price": { "type": "string", "nullable": true, "description": "Upper bound for the retail price, in dollars. This is typically only used for variable-priced gift cards.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "min_customer_age": { "type": "integer", "nullable": true, "description": "Minimum customer age, in years, required to purchase." }, "minimum_retail_price": { "type": "string", "nullable": true, "description": "Lower bound for the retail price, in dollars. This is typically only used for variable-priced gift cards.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "name": { "type": "string", "description": "Human-readable product name." }, "prompt_for_quantity": { "type": "boolean", "description": "Whether the register prompts for a quantity when the product is scanned." }, "retail_price": { "type": "string", "nullable": true, "description": "Current shelf/retail price in dollars.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "sold_by_weight": { "type": "boolean", "description": "Whether the product is sold by weight rather than by unit." }, "store_id": { "type": "string", "description": "ID of the store this product belongs to.", "pattern": "^[0-9]+$" }, "store_vendor_products": { "description": "Vendor catalog entries for this product.", "type": "array", "items": { "$ref": "#/components/schemas/CompactStoreVendorProduct" } }, "sync_to_deli_scales": { "type": "boolean", "default": false, "description": "Whether the product is synchronized to deli scales." }, "target_margin": { "type": "string", "nullable": true, "description": "Target gross margin for pricing decisions, as a whole-number percentage (35 means 35%).", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "tax_rates": { "description": "Tax rates applied to this product at the register.", "type": "array", "items": { "$ref": "#/components/schemas/CompactTaxRate" } }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" }, "variable_sale_price": { "type": "boolean", "description": "Whether the sale price is entered at the register instead of fixed." }, "variable_weights": { "description": "Preset weights for products sold by weight.", "type": "array", "items": { "$ref": "#/components/schemas/CompactVariableWeight" } }, "wic_enabled": { "type": "boolean", "description": "Whether the product is eligible for WIC payment." } }, "description": "A product as it is sold at a single store, carrying its price, barcodes, department, and inventory settings.", "required": [ "id", "active", "barcode", "brand", "country_of_origin", "created_at", "department_id", "description", "ebt_enabled", "ecommerce_enabled", "food_modifier_categories", "images", "is_blackhawk_gift_card", "is_reloadable_blackhawk_gift_card", "is_tippable", "item_modifiers", "loyalty_points_per_dollar", "manual_item", "maximum_retail_price", "min_customer_age", "minimum_retail_price", "name", "prompt_for_quantity", "retail_price", "sold_by_weight", "store_id", "sync_to_deli_scales", "target_margin", "tax_rates", "updated_at", "variable_sale_price", "variable_weights", "wic_enabled" ] }, "StoreProductInventory": { "type": "object", "properties": { "id": { "type": "string", "description": "Store product ID", "pattern": "^[0-9]+$" }, "barcode": { "type": "string", "description": "Barcode scanned at the register for this product." }, "current": { "type": "string", "nullable": true, "description": "Quantity currently on hand. Goes negative when sales outrun the last count. Null when the product has never been counted.", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "store_department_id": { "type": "string", "description": "The department the product belongs to.", "pattern": "^[0-9]+$" }, "store_id": { "type": "string", "description": "The store the product belongs to.", "pattern": "^[0-9]+$" }, "updated_at": { "type": "string", "nullable": true, "description": "When the on-hand quantity was last written, regardless of the date the change applies to. A count entered today but dated last week carries today. Null when the product has never been counted.", "format": "date-time" } }, "description": "A store product's current on-hand quantity.", "required": [ "id", "barcode", "current", "store_department_id", "store_id", "updated_at" ] }, "StoreProductInventoryList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreProductInventory" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "description": "A page of store product inventory.", "required": [ "data", "has_more" ] }, "StoreProductList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreProduct" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "required": [ "data", "has_more" ] }, "StoreProductLoaders": { "type": "string", "enum": [ "active_vendor", "active_vendor_product", "inventory", "store_vendor_products" ] }, "StoreProductPriceInputMethod": { "type": "string", "enum": [ "COST_FILE", "MANUALLY_ENTERED_PRICE", "USED_SUGGESTED_PRICE" ] }, "StoreProductPriceSource": { "type": "string", "enum": [ "ACCEPTED_COST_CHANGE", "BULK_UPDATE", "COST_FILE_IMPORT", "PRODUCT_DETAILS", "PRODUCT_RULES" ] }, "StoreProductPriceSourcePlatform": { "type": "string", "enum": [ "API", "CDC_PIPELINE", "CLI", "MOBILE", "WEB" ] }, "StoreProductSelectionCriteria": { "type": "object", "properties": { "barcodes": { "maxItems": 1000, "description": "Barcodes to select. A barcode carried by products in several stores selects all of them unless store_id is supplied.", "type": "array", "items": { "type": "string" } }, "ids": { "maxItems": 1000, "description": "Store product IDs to select.", "type": "array", "items": { "type": "string", "pattern": "^[0-9]+$" } }, "store_id": { "type": "string", "description": "Restricts the selection to one store. Omit to select matching products across the whole banner.", "pattern": "^[0-9]+$" } }, "description": "Selects the store products a request applies to." }, "StoreVendorProductIdentifierType": { "type": "string", "enum": [ "barcode", "description", "item_code" ] }, "TaxRate": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "active": { "type": "boolean", "description": "Whether the rate is charged at checkout. An inactive rate stays configured but is not applied." }, "category": { "description": "The kind of tax this rate represents.", "allOf": [ { "$ref": "#/components/schemas/TaxRateCategory" } ] }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "name": { "type": "string", "description": "Name of the tax rate, such as the jurisdiction that levies it or the category it covers." }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" }, "value": { "type": "string", "description": "The rate charged. When `value_type` is `percentage`, this is a percentage of the taxable amount — `8.25` means 8.25%. When it is `amount`, this is a fixed amount of currency charged per unit sold.", "example": "8.25", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "value_type": { "description": "How `value` is applied: a fixed amount or a percentage.", "allOf": [ { "$ref": "#/components/schemas/TaxRateValueType" } ] } }, "description": "A tax applied to products at a store, charged as a flat amount or a percentage.", "required": [ "id", "active", "category", "created_at", "name", "updated_at", "value", "value_type" ] }, "TaxRateCategory": { "type": "string", "description": "The kind of tax a rate represents.", "enum": [ "other", "sales" ] }, "TaxRateList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaxRate" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "required": [ "data", "has_more" ] }, "TaxRateValueType": { "type": "string", "description": "How a tax rate applies its value: a fixed amount per unit sold, or a percentage of the taxable amount.", "enum": [ "amount", "percentage" ] }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "cashback_amount": { "type": "string", "description": "Cash back requested by the shopper.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "completed_at": { "type": "string", "description": "Date and time when the transaction was finalized.", "format": "date-time" }, "coupon_total": { "type": "string", "description": "Total savings from coupons.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "discount_total": { "type": "string", "description": "Total savings from manual or employee discounts.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "employee_id": { "type": "string", "description": "ID of the employee who processed the transaction.", "pattern": "^[0-9]+$" }, "external_id": { "type": "string", "nullable": true, "description": "Your own identifier for the transaction, as supplied when it was recorded." }, "gift_card_sales": { "description": "Gift cards purchased in the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionGiftCardSale" } }, "gift_card_sales_total": { "type": "string", "description": "Total face value of gift cards purchased in the transaction.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "issued_coupons": { "description": "Coupons issued to the shopper by the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionIssuedCoupon" } }, "item_modifier_total": { "type": "string", "description": "Total value of item modifiers.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "lane_id": { "type": "string", "description": "ID of the checkout lane that processed the transaction.", "pattern": "^[0-9]+$" }, "line_items": { "description": "Product line items included in the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItem" } }, "loyalty_rewards_total": { "type": "string", "description": "Total savings from loyalty reward redemptions.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "metadata": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 }, "example": { "order_source": "shopify", "fulfillment_id": "88213" }, "nullable": true, "description": "Your own key/value pairs, exactly as supplied when the transaction was recorded." }, "payments": { "description": "Payments collected for the transaction.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionPayment" } }, "promo_savings": { "type": "string", "description": "Total savings from promotions.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "promo_total": { "type": "string", "description": "Sum of line-item totals after promotions are applied.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "receipt_type": { "nullable": true, "description": "How the shopper took their receipt, or null when they took none.", "allOf": [ { "$ref": "#/components/schemas/ReceiptType" } ] }, "refund_total": { "type": "string", "description": "Total value refunded against this transaction.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "refunds": { "description": "Refunds of the transaction. Retrieve one with `GET /v1/transactions/{id}` for the products returned and how the money went back.", "type": "array", "items": { "$ref": "#/components/schemas/CompactRefund" } }, "retail_total": { "type": "string", "description": "Sum of line-item retail totals after promotions and before discounts and tax.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "shopper_facing_id": { "type": "string", "description": "Human-readable transaction identifier shown to the shopper." }, "shopper_id": { "type": "string", "nullable": true, "description": "ID of the loyalty shopper associated with the transaction, or null for an anonymous transaction.", "format": "uuid" }, "source": { "description": "Where the transaction came from.", "allOf": [ { "$ref": "#/components/schemas/TransactionSource" } ] }, "started_at": { "type": "string", "description": "Date and time when the cashier started the transaction.", "format": "date-time" }, "status": { "description": "Current lifecycle status of the transaction.", "allOf": [ { "$ref": "#/components/schemas/TransactionStatus" } ] }, "store_id": { "type": "string", "description": "ID of the store where the transaction was placed.", "pattern": "^[0-9]+$" }, "subtotal": { "type": "string", "description": "Sum of line-item subtotals before promotions, discounts, and tax.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "tax_total": { "type": "string", "description": "Total tax charged on the transaction.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "taxable_amount": { "type": "string", "description": "Portion of the transaction subject to tax.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "tip_amount": { "type": "string", "description": "Tip added by the shopper.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "total": { "type": "string", "description": "Final transaction amount including tax. Sales are positive and refunds are negative.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "total_collected": { "type": "string", "description": "Total collected from the shopper, including the transaction total, tip, and cash back.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "type": { "description": "Financial transaction type represented by the transaction.", "allOf": [ { "$ref": "#/components/schemas/TransactionType" } ] } }, "description": "A completed checkout at a store, covering the lane, cashier, and shopper, the products sold, the savings applied, the payments collected, and any refunds against it.", "required": [ "id", "cashback_amount", "completed_at", "coupon_total", "discount_total", "employee_id", "external_id", "gift_card_sales", "gift_card_sales_total", "issued_coupons", "item_modifier_total", "lane_id", "line_items", "loyalty_rewards_total", "metadata", "payments", "promo_savings", "promo_total", "receipt_type", "refund_total", "refunds", "retail_total", "shopper_facing_id", "shopper_id", "source", "started_at", "status", "store_id", "subtotal", "tax_total", "taxable_amount", "tip_amount", "total", "total_collected", "type" ] }, "TransactionAlreadyExistsError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_already_exists" ] }, "error_details": { "$ref": "#/components/schemas/TransactionAlreadyExistsErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionAlreadyExistsErrorDetails": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "TransactionEmployeeNotFoundError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_employee_not_found" ] }, "error_details": { "$ref": "#/components/schemas/TransactionEmployeeNotFoundErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionEmployeeNotFoundErrorDetails": { "type": "object", "properties": { "employee_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "employee_id" ] }, "TransactionEmployeeNotVirtualError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_employee_not_virtual" ] }, "error_details": { "$ref": "#/components/schemas/TransactionEmployeeNotVirtualErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionEmployeeNotVirtualErrorDetails": { "type": "object", "properties": { "employee_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "employee_id" ] }, "TransactionGiftCardSale": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "amount": { "type": "string", "description": "Amount loaded onto the gift card.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "gift_card_id": { "type": "string", "nullable": true, "description": "ID of the associated GiftCard that was funded by this sale. This value may be `null` if the sale was made while the POS was offline, and the transaction has not yet been back-filled." }, "gift_card_transaction_id": { "type": "string", "nullable": true, "description": "ID of the associated GiftCardTransaction that funded the gift card. This value may be `null` if the sale was made while the POS was offline, and the transaction has not yet been back-filled." } }, "description": "A gift card purchased on a transaction, with the amount loaded onto it and links to the gift card and the transaction that funded it.", "required": [ "id", "amount", "gift_card_id", "gift_card_transaction_id" ] }, "TransactionIssuedCoupon": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "coupon_code": { "type": "string", "description": "Coupon code the shopper presents to redeem the coupon on a later transaction." }, "coupon_id": { "type": "string", "description": "ID of the coupon that was issued." }, "ended_at": { "type": "string", "description": "Date and time after which the coupon can no longer be redeemed.", "format": "date-time" }, "offer_benefit_value": { "type": "string", "description": "Value of the coupon to the shopper when redeemed.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "snap_incentive_program_id": { "type": "string", "nullable": true, "description": "ID of the SNAP incentive program the coupon was issued under." }, "started_at": { "type": "string", "description": "Date and time from which the coupon can be redeemed.", "format": "date-time" } }, "description": "A coupon issued to the shopper by a transaction, with its code, benefit value, and the window in which it can be redeemed.", "required": [ "id", "coupon_code", "coupon_id", "ended_at", "offer_benefit_value", "snap_incentive_program_id", "started_at" ] }, "TransactionItemModifiersNotFoundError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_item_modifiers_not_found" ] }, "error_details": { "$ref": "#/components/schemas/TransactionItemModifiersNotFoundErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionItemModifiersNotFoundErrorDetails": { "type": "object", "properties": { "item_modifier_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]+$" } } }, "required": [ "item_modifier_ids" ] }, "TransactionLaneNotFoundError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_lane_not_found" ] }, "error_details": { "$ref": "#/components/schemas/TransactionLaneNotFoundErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionLaneNotFoundErrorDetails": { "type": "object", "properties": { "lane_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "lane_id" ] }, "TransactionLaneNotVirtualError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_lane_not_virtual" ] }, "error_details": { "$ref": "#/components/schemas/TransactionLaneNotVirtualErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionLaneNotVirtualErrorDetails": { "type": "object", "properties": { "lane_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "lane_id" ] }, "TransactionLaneStoreMismatchError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_lane_store_mismatch" ] }, "error_details": { "$ref": "#/components/schemas/TransactionLaneStoreMismatchErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionLaneStoreMismatchErrorDetails": { "type": "object", "properties": { "lane_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "lane_id" ] }, "TransactionLineItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "coupon_total": { "type": "string", "description": "Total savings from coupons on this line.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "coupons": { "description": "Coupons applied to this line.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemCoupon" } }, "department_id": { "type": "string", "description": "ID of the department the product is assigned to." }, "discount_total": { "type": "string", "description": "Total savings from manual and employee discounts on this line.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "discounts": { "description": "Manual and employee discounts applied to this line.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemDiscount" } }, "ebt_tax_waived_total": { "type": "string", "description": "Tax waived on this line because the product was paid for with EBT.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "free_quantity": { "type": "string", "description": "Portion of the quantity on this line given away free by a promotion.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "item_modifier_total": { "type": "string", "description": "Total of the fees and deposits charged on this line, such as bottle deposits and container redemption fees.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "item_modifiers": { "description": "Fees and deposits charged on this line, such as bottle deposits, container redemption fees, and bag fees.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemModifier" } }, "loyalty_rewards": { "description": "Loyalty rewards redeemed against this line.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemLoyaltyReward" } }, "loyalty_rewards_total": { "type": "string", "description": "Total savings from loyalty reward redemptions on this line.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "product": { "description": "Product sold on this line.", "allOf": [ { "$ref": "#/components/schemas/TransactionLineItemProduct" } ] }, "promo_savings": { "type": "string", "description": "Total savings from promotions on this line.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "promotions": { "description": "Promotions applied to this line.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemPromotion" } }, "quantity": { "type": "string", "description": "Number of units sold on this line, or the weight sold for products priced by weight.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "refunded_order_line_item_id": { "type": "string", "nullable": true, "description": "ID of the original sale line this refund line returns, or null when this line is not a refund." }, "retail_price": { "type": "string", "description": "Shelf price per unit before promotions, coupons, and discounts.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "retail_total": { "type": "string", "description": "Line total after promotions are applied, before discounts and tax.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "subtotal": { "type": "string", "description": "Retail price multiplied by quantity, before promotions, discounts, and tax.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "tax_total": { "type": "string", "description": "Total sales tax charged on this line.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "taxable_amount": { "type": "string", "description": "Portion of this line that is subject to tax.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "taxes": { "description": "Sales taxes charged on this line.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemTax" } }, "total": { "type": "string", "description": "Final amount for this line, including tax. Positive on a sale and negative on a refund.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "transaction_type": { "deprecated": true, "description": "Deprecated. Use `type`.", "allOf": [ { "$ref": "#/components/schemas/TransactionType" } ] }, "type": { "description": "Whether this line was sold, refunded, or voided.", "allOf": [ { "$ref": "#/components/schemas/TransactionType" } ] }, "variable_weights": { "description": "Weight readings recorded for this line when the product is sold by weight.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemVariableWeight" } }, "wic_adjusted_price": { "type": "string", "nullable": true, "description": "Price per unit the shopper paid under WIC, or null when WIC was not applied to this line.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" } }, "description": "A product sold on a transaction, with its quantity, price, and totals, plus the coupons, discounts, loyalty rewards, promotions, fees, taxes, and weight readings recorded against it.", "required": [ "id", "coupon_total", "coupons", "department_id", "discount_total", "discounts", "ebt_tax_waived_total", "free_quantity", "item_modifier_total", "item_modifiers", "loyalty_rewards", "loyalty_rewards_total", "product", "promo_savings", "promotions", "quantity", "refunded_order_line_item_id", "retail_price", "retail_total", "subtotal", "tax_total", "taxable_amount", "taxes", "total", "transaction_type", "type", "variable_weights", "wic_adjusted_price" ] }, "TransactionLineItemCoupon": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "applied_amount": { "type": "string", "description": "Savings the coupon produced on this line item.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "coupon_code": { "type": "string", "description": "Coupon code that was scanned or entered at checkout." }, "coupon_id": { "type": "string", "description": "ID of the coupon that was redeemed." }, "offer_display_text": { "type": "string", "description": "Offer text shown on the receipt for the coupon." }, "offer_id": { "type": "string", "description": "ID of the offer the coupon came from." } }, "description": "A coupon redeemed against a line of a transaction, with the savings it produced and the offer it came from.", "required": [ "id", "applied_amount", "coupon_code", "coupon_id", "offer_display_text", "offer_id" ] }, "TransactionLineItemDiscount": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "applied_amount": { "type": "string", "description": "Savings the discount produced on this line item.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "discount_id": { "type": "string", "nullable": true, "description": "ID of the discount that was applied, or null when the cashier entered a one-off discount." }, "discount_name": { "type": "string", "description": "Name of the discount shown to the cashier and on the receipt." }, "discount_type": { "description": "How the discount is calculated: a percentage off or a fixed amount off.", "allOf": [ { "$ref": "#/components/schemas/DiscountType" } ] }, "discount_value": { "type": "string", "description": "Configured value of the discount, such as 10 for 10% off or 1.50 for $1.50 off.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "A discount applied to a line of a transaction, with its name, type, configured value, and the savings it produced.", "required": [ "id", "applied_amount", "discount_id", "discount_name", "discount_type", "discount_value" ] }, "TransactionLineItemInvalidError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_invalid_line_item" ] }, "error_details": { "$ref": "#/components/schemas/TransactionLineItemInvalidErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionLineItemInvalidErrorDetails": { "type": "object", "properties": { "reason": { "allOf": [ { "$ref": "#/components/schemas/TransactionLineItemInvalidReason" } ] }, "store_product_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "reason", "store_product_id" ] }, "TransactionLineItemInvalidReason": { "type": "string", "enum": [ "item_modifier_not_on_line", "non_integer_quantity", "retail_price_mismatch", "weight_on_non_weight_item", "weight_quantity_must_be_one", "weight_required" ] }, "TransactionLineItemLoyaltyReward": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "applied_amount": { "type": "string", "description": "Savings the loyalty reward produced on this line item.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "loyalty_reward_id": { "type": "string", "description": "ID of the loyalty reward that was redeemed." }, "loyalty_reward_name": { "type": "string", "description": "Name of the loyalty reward at the time it was redeemed." }, "offer_id": { "type": "string", "description": "ID of the offer associated with the loyalty reward." }, "order_loyalty_reward_id": { "type": "string", "description": "ID of the transaction-level reward redemption this line item draws from." } }, "description": "A loyalty reward redeemed against a line of a transaction, with the savings it produced and the offer it came from.", "required": [ "id", "applied_amount", "loyalty_reward_id", "loyalty_reward_name", "offer_id", "order_loyalty_reward_id" ] }, "TransactionLineItemModifier": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "amount": { "type": "string", "description": "Amount charged for the fee or deposit on this line item.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "item_modifier_id": { "type": "string", "description": "ID of the fee or deposit that was charged, such as a bottle deposit or CRV.", "pattern": "^[0-9]+$" }, "quantity": { "type": "string", "description": "Number of units of the fee or deposit charged on this line item.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "tax_amount": { "type": "string", "description": "Tax charged on the fee or deposit.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "taxes": { "description": "Taxes charged on the fee or deposit.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionLineItemTax" } } }, "description": "A fee or deposit charged on a line of a transaction, with the amount, quantity, and tax collected on it.", "required": [ "id", "amount", "item_modifier_id", "quantity", "tax_amount", "taxes" ] }, "TransactionLineItemProduct": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the product in your store's catalog." }, "barcode": { "type": "string", "description": "UPC or PLU recorded for the product when it was sold, whether it was scanned or entered by hand." }, "brand": { "type": "string", "nullable": true, "description": "Brand of the product." }, "ebt_enabled": { "type": "boolean", "description": "Whether the product can be paid for with EBT." }, "name": { "type": "string", "description": "Name of the product as it was sold." }, "sold_by_weight": { "type": "boolean", "description": "Whether the product is priced by weight rather than by unit." }, "unit_of_measure": { "type": "string", "nullable": true, "description": "Unit of measure the size is expressed in, such as oz or lb." }, "unit_of_measure_amount": { "type": "string", "nullable": true, "description": "Size of the product in its unit of measure, such as 12 for a 12 oz can.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "wic_enabled": { "type": "boolean", "description": "Whether the product can be paid for with WIC." } }, "description": "The product sold on a line of a transaction, along with the cost the store paid for it when known.", "required": [ "id", "barcode", "brand", "ebt_enabled", "name", "sold_by_weight", "unit_of_measure", "unit_of_measure_amount", "wic_enabled" ] }, "TransactionLineItemPromotion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "amount": { "type": "string", "description": "Portion of the line the promotion applied to.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "display_text": { "type": "string", "nullable": true, "description": "Text shown for the promotion on the receipt." }, "offer_id": { "type": "string", "description": "ID of the offer the promotion belongs to.", "pattern": "^[0-9]+$" }, "promotion_id": { "type": "string", "description": "ID of the promotion that produced the savings.", "pattern": "^[0-9]+$" }, "savings": { "type": "string", "description": "Amount the promotion took off the line.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "A promotion applied to a line of a transaction, with the savings it produced, the amount it covered, and the text shown on the receipt.", "required": [ "id", "amount", "display_text", "offer_id", "promotion_id", "savings" ] }, "TransactionLineItemTax": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "amount": { "type": "string", "description": "Tax charged on this line item.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "tax_rate": { "description": "Tax rate that produced the charge, as it was configured when the transaction was completed.", "allOf": [ { "$ref": "#/components/schemas/CompactTaxRate" } ] } }, "description": "Tax charged on a line of a transaction, with the amount collected and the tax rate that produced it.", "required": [ "id", "amount", "tax_rate" ] }, "TransactionLineItemVariableWeight": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "variable_weight": { "description": "Tare container weight subtracted from the scale reading, as it was recorded at the time of sale.", "allOf": [ { "$ref": "#/components/schemas/CompactVariableWeight" } ] } }, "description": "An individual weight reading captured for a line of a transaction sold by weight.", "required": [ "id", "variable_weight" ] }, "TransactionPayment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "authorized_amount": { "type": "string", "description": "Amount authorized for this payment, which is less than the requested amount on a partial approval.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "card_brand": { "nullable": true, "description": "Card network used for the payment, or null for non-card payments.", "allOf": [ { "$ref": "#/components/schemas/CardBrand" } ] }, "card_last4": { "type": "string", "nullable": true, "minLength": 4, "maxLength": 4, "description": "Last four digits of the card used, or null for non-card payments.", "pattern": "^[0-9]+$" }, "cash_received": { "type": "string", "nullable": true, "description": "Cash handed over by the shopper, or null for non-cash payments.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "cashback_amount": { "type": "string", "description": "Cash back included in this payment.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "change_returned": { "type": "string", "nullable": true, "description": "Change given back to the shopper, or null for non-cash payments.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "completed_at": { "type": "string", "description": "Date and time when the payment was completed.", "format": "date-time" }, "payment_type": { "description": "How the payment was tendered.", "allOf": [ { "$ref": "#/components/schemas/TransactionPaymentType" } ] }, "requested_amount": { "type": "string", "description": "Amount requested for this payment.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "reversals": { "description": "Reversals recorded against this payment.", "type": "array", "items": { "$ref": "#/components/schemas/TransactionPaymentReversal" } }, "terminal_was_online": { "type": "boolean", "nullable": true, "description": "Indicates if the payment terminal was online when the payment was authorized. This will be `null` for non-card payments." }, "till_id": { "type": "string", "nullable": true, "description": "ID of the till the payment was collected into, or null when the payment was not tied to a till.", "format": "uuid" }, "tip_amount": { "type": "string", "description": "Tip included in this payment.", "format": "monetary", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" } }, "description": "A payment collected on a transaction, covering how it was tendered, the amounts requested and authorized, any tip or cash back, the till it was paid into, and any reversals against it.", "required": [ "id", "authorized_amount", "card_brand", "card_last4", "cash_received", "cashback_amount", "change_returned", "completed_at", "payment_type", "requested_amount", "reversals", "terminal_was_online", "till_id", "tip_amount" ] }, "TransactionPaymentReversal": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "authorized_amount": { "type": "string", "description": "Amount actually released.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "card_brand": { "nullable": true, "description": "Card network used for the reversed payment, or null for non-card payments.", "allOf": [ { "$ref": "#/components/schemas/CardBrand" } ] }, "card_last4": { "type": "string", "nullable": true, "minLength": 4, "maxLength": 4, "description": "Last four digits of the card used for the reversed payment, or null for non-card payments.", "pattern": "^[0-9]+$" }, "completed_at": { "type": "string", "description": "Date and time when the reversal was completed.", "format": "date-time" }, "payment_type": { "description": "How the reversed payment was tendered.", "allOf": [ { "$ref": "#/components/schemas/TransactionPaymentType" } ] }, "requested_amount": { "type": "string", "description": "Amount requested to be released.", "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "A reversal of a payment collected on a transaction, with the amount requested, the amount released, and how the payment was tendered.", "required": [ "id", "authorized_amount", "card_brand", "card_last4", "completed_at", "payment_type", "requested_amount" ] }, "TransactionPaymentType": { "type": "string", "enum": [ "cash", "cash_app", "check", "credit", "debit", "donation", "doordash", "ebt_cash", "ebt_foodstamp", "ecommerce", "ewic", "gift_card", "gift_certificate", "grubhub", "house_account", "instacart", "lottery_payout", "mfg_coupon", "money_transfer", "moneygram", "paypal", "qr_pay", "ria_money_transfer", "state_voucher", "uber_eats", "venmo", "western_union", "zelle" ] }, "TransactionRequestMismatchError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_request_mismatch" ] }, "error_details": { "$ref": "#/components/schemas/TransactionRequestMismatchErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionRequestMismatchErrorDetails": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "fields" ] }, "TransactionShopperNotFoundError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_shopper_not_found" ] }, "error_details": { "$ref": "#/components/schemas/TransactionShopperNotFoundErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionShopperNotFoundErrorDetails": { "type": "object", "properties": { "shopper_id": { "type": "string", "format": "uuid" } }, "required": [ "shopper_id" ] }, "TransactionSource": { "type": "string", "enum": [ "api", "migration", "pos" ] }, "TransactionStatus": { "type": "string", "enum": [ "completed", "expired", "suspended", "voided" ] }, "TransactionStoreProductsNotFoundError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_store_products_not_found" ] }, "error_details": { "$ref": "#/components/schemas/TransactionStoreProductsNotFoundErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionStoreProductsNotFoundErrorDetails": { "type": "object", "properties": { "store_product_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]+$" } } }, "required": [ "store_product_ids" ] }, "TransactionTotalsMismatchError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "transaction_totals_mismatch" ] }, "error_details": { "$ref": "#/components/schemas/TransactionTotalsMismatchErrorDetails" } }, "required": [ "error_code", "error_details" ] }, "TransactionTotalsMismatchErrorDetails": { "type": "object", "properties": { "actual": { "type": "string" }, "expected": { "type": "string" }, "field": { "allOf": [ { "$ref": "#/components/schemas/TransactionTotalsMismatchField" } ] }, "store_product_id": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "actual", "expected", "field" ] }, "TransactionTotalsMismatchField": { "type": "string", "enum": [ "line_total", "order_total", "payments_total", "tax_total" ] }, "TransactionType": { "type": "string", "enum": [ "refund", "sale", "void" ] }, "TransactionsList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "description": "A page of transactions.", "required": [ "data", "has_more" ] }, "UnauthorizedBannerError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "unauthorized_banner" ] } }, "required": [ "error_code" ] }, "UnauthorizedStoreError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "unauthorized_store" ] } }, "required": [ "error_code" ] }, "UnsupportedStateFieldError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "unsupported_state_field" ] } }, "required": [ "error_code" ] }, "UpdateDiscountRequest": { "type": "object", "properties": { "amount": { "type": "string", "description": "Discount value as a decimal string. For `amount_off`, this is in major/minor currency units (for example, \"1.25\"). For `percentage_off`, this is a whole-number percentage (`\"1.00\"` means 1%).", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "name": { "type": "string", "nullable": true, "description": "Human-readable discount name, or null when the discount is unnamed." }, "type": { "description": "How `amount` is applied: as a fixed monetary reduction or a percentage reduction.", "allOf": [ { "$ref": "#/components/schemas/DiscountType" } ] } } }, "UpdateEmployeeRequest": { "type": "object", "properties": { "authentication_rule": { "nullable": true, "default": null, "description": "How the employee signs in at the point of sale, or null to sign in with a PIN. Every method the rule names must have its credential set on the employee.", "allOf": [ { "$ref": "#/components/schemas/AuthenticationRule" } ] }, "badge_barcode": { "type": "string", "nullable": true, "default": null, "description": "Barcode on the badge the employee scans to sign in at the point of sale, or null for none. Unique within the banner. A deactivated employee cannot hold one unless the same request reactivates them." }, "deactivated_at": { "type": "string", "nullable": true, "description": "When the employee was deactivated. Null means active, so setting it back to null reactivates the employee. Deactivating releases the employee's PIN and barcode so another employee can take them.", "format": "date-time" }, "email_address": { "type": "string", "nullable": true, "default": null, "description": "Employee's email address, or null for none. Unique within the banner.", "format": "email", "maxLength": 254 }, "first_name": { "type": "string", "description": "Employee's first name." }, "last_name": { "type": "string", "description": "Employee's last name." }, "pin": { "type": "string", "nullable": true, "default": null, "minLength": 6, "maxLength": 6, "description": "Numeric PIN the employee enters to sign in at the point of sale, or null for none. Six digits, and unique within the banner. A deactivated employee cannot hold one unless the same request reactivates them.", "pattern": "^[0-9]+$" }, "roles": { "description": "Roles the employee holds. Supplying this replaces every role the employee holds.", "maxItems": 200, "type": "array", "items": { "$ref": "#/components/schemas/UpdateEmployeeRole" } } }, "description": "Values for updating an employee. An omitted property is left unchanged, and an explicit null clears a property that permits one." }, "UpdateEmployeeRole": { "type": "object", "properties": { "name": { "description": "The role to grant.", "allOf": [ { "$ref": "#/components/schemas/AssignableRoleName" } ] }, "store_id": { "type": "string", "nullable": true, "description": "The store the role applies at, or null to apply it at every store in the banner.", "pattern": "^[0-9]+$" } }, "description": "A role to grant an employee, and the store it applies at.", "required": [ "name" ] }, "UpdateItemModifierRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable item modifier name." }, "price_tag_label": { "nullable": true, "description": "Optional shelf-tag classification for bottle deposits or container redemption value.", "allOf": [ { "$ref": "#/components/schemas/PriceTagModifier" } ] }, "tax_behavior": { "description": "Whether the modifier is excluded from tax or inherits the product tax behavior.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierTaxBehavior" } ] }, "type": { "description": "Business purpose of the item modifier.", "allOf": [ { "$ref": "#/components/schemas/ItemModifierType" } ] }, "value": { "type": "string", "description": "Monetary value of the modifier as a decimal string in major/minor currency units.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } } }, "UpdateShopperRequest": { "type": "object", "properties": { "email_address": { "type": "string", "nullable": true, "description": "Email address on file for the shopper.", "format": "email", "maxLength": 254 }, "enrolled_in_loyalty_program": { "type": "boolean", "default": false, "description": "Whether the shopper is enrolled in the loyalty program. Shoppers must explicitly opt into the loyalty program, typically at the POS. Digital gift card recipients are also stored as shoppers, but are only opted into the loyalty program after giving explicit permission." }, "first_name": { "type": "string", "nullable": true, "description": "Given name of the shopper." }, "last_name": { "type": "string", "nullable": true, "description": "Family name of the shopper." }, "phone_number": { "type": "string", "description": "Phone number on file for the shopper, and what a loyalty member gives at checkout to be identified.", "format": "phone", "pattern": "^\\+[1-9]\\d{1,14}$" }, "postal_code": { "type": "string", "nullable": true, "description": "Postal code on file for the shopper." } } }, "UpdateStoreDepartmentRequest": { "type": "object", "properties": { "deactivated_at": { "type": "string", "nullable": true, "description": "When the department was deactivated. Null means active, so setting it reactivates the department.", "format": "date-time" }, "exclude_from_sales_reporting": { "type": "boolean", "description": "Whether sales from this department are omitted from sales reporting." }, "name": { "type": "string", "description": "Human-readable department name." }, "parent_department_id": { "type": "string", "nullable": true, "description": "ID of the parent department, or null for a top-level department. A parent must itself be top-level: departments nest one level deep.", "pattern": "^[0-9]+$" } } }, "UpdateStoreProduct": { "type": "object", "properties": { "active": { "type": "boolean", "default": true }, "active_store_vendor_product_id": { "type": "string", "pattern": "^-?[0-9]+$" }, "alcohol_by_volume": { "type": "string", "nullable": true, "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "barcode": { "type": "string" }, "brand": { "type": "string", "nullable": true }, "case_size": { "type": "integer", "nullable": true }, "country_of_origin": { "type": "string", "nullable": true, "maxLength": 3, "minLength": 3 }, "department_id": { "type": "string", "pattern": "^-?[0-9]+$" }, "description": { "type": "string", "nullable": true }, "disable_barcode_sanitization": { "type": "boolean", "description": "When true, the barcode is stored verbatim and the product's `barcode_type` is set to `Unsanitized`. When false, an existing `Unsanitized` product is re-sanitized on save. When omitted, the existing `barcode_type` is preserved (partial updates are safe)." }, "discount_restrictions": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/DiscountRestriction" } }, "ebt_enabled": { "type": "boolean", "default": false }, "ecommerce_enabled": { "type": "boolean", "default": false }, "food_modifier_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "ingredients": { "type": "string", "nullable": true }, "is_blackhawk_gift_card": { "type": "boolean", "default": false }, "is_reloadable_blackhawk_gift_card": { "type": "boolean", "default": false }, "is_tippable": { "type": "boolean", "default": false }, "item_modifier_ids": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+$" } }, "last_printed_at": { "type": "string", "nullable": true, "format": "date-time" }, "loyalty_points_per_dollar": { "type": "string", "nullable": true, "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "manual_item": { "type": "boolean", "default": false }, "maximum_retail_price": { "type": "string", "nullable": true, "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "min_customer_age": { "type": "integer" }, "minimum_retail_price": { "type": "string", "nullable": true, "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "name": { "type": "string" }, "notes": { "type": "string", "nullable": true }, "pack_size": { "type": "integer", "nullable": true }, "primary_vendor_configuration": { "allOf": [ { "$ref": "#/components/schemas/PrimaryVendorConfiguration" } ] }, "print_physical_tag": { "type": "boolean", "default": false }, "prompt_for_quantity": { "type": "boolean", "default": false }, "retail_price": { "type": "string", "nullable": true, "format": "positive-monetary", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "retail_price_input_method": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoreProductPriceInputMethod" } ] }, "retail_price_source": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoreProductPriceSource" } ] }, "retail_price_source_platform": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/StoreProductPriceSourcePlatform" } ] }, "retail_price_unit_of_measure_id": { "type": "string", "nullable": true, "pattern": "^-?[0-9]+$" }, "shelf_life_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 999, "description": "Shelf life in days sent to deli scales (Hobart, eplum, Ishida); the scale computes the sell-by date from it. 1-999, or null for no Vori-managed shelf life." }, "snap_incentive_earnable": { "type": "boolean", "default": false }, "snap_incentive_redeemable": { "type": "boolean", "default": false }, "sold_by_weight": { "type": "boolean", "default": false }, "store_product_group_rule_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "store_vendor_products": { "type": "array", "items": { "$ref": "#/components/schemas/CompactSetStoreVendorProduct" } }, "sync_to_deli_scales": { "type": "boolean", "default": false }, "target_margin": { "type": "number", "nullable": true }, "tax_rate_ids": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+$" } }, "unit_volume_quantity": { "type": "string", "nullable": true, "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" }, "unit_volume_uom_name": { "type": "string", "nullable": true }, "variable_sale_price": { "type": "boolean", "default": false }, "variable_weight_ids": { "type": "array", "items": { "type": "string", "pattern": "^-?[0-9]+$" } }, "wic_enabled": { "type": "boolean", "default": false }, "wic_override_plu": { "type": "string", "nullable": true } } }, "UpdateStoreProductRequest": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UpdateStoreProduct" } }, "required": [ "data" ] }, "UpdateTaxRateRequest": { "type": "object", "properties": { "active": { "type": "boolean", "default": true, "description": "Whether the rate is charged at checkout. An inactive rate stays configured but is not applied." }, "category": { "description": "The kind of tax this rate represents.", "allOf": [ { "$ref": "#/components/schemas/TaxRateCategory" } ] }, "name": { "type": "string", "description": "Name of the tax rate, such as the jurisdiction that levies it or the category it covers." }, "value": { "type": "string", "description": "The rate charged. When `value_type` is `percentage`, this is a percentage of the taxable amount — `8.25` means 8.25%. When it is `amount`, this is a fixed amount of currency charged per unit sold.", "example": "8.25", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "value_type": { "description": "How `value` is applied: a fixed amount or a percentage.", "allOf": [ { "$ref": "#/components/schemas/TaxRateValueType" } ] } } }, "UpdateVariableWeightRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Human-readable name for the tare container, such as \"Produce bag\"." }, "unit_of_measure": { "description": "Unit of measure the weight is expressed in, limited to the units the point of sale can weigh in.", "allOf": [ { "$ref": "#/components/schemas/VariableWeightUnit" } ] }, "value": { "type": "string", "description": "Weight of the tare container, as a decimal string in the unit of measure.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } } }, "UpsertStoreProductInventoryRequest": { "type": "object", "properties": { "inventory": { "description": "The change to make to the on-hand quantity. Omit it to update only the reorder levels.", "allOf": [ { "$ref": "#/components/schemas/InventoryUpdate" } ] }, "max_stock": { "type": "string", "nullable": true, "description": "The most of this product the store wants on hand. Send null to clear it; omit it to leave it as it is.", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "min_par": { "type": "string", "nullable": true, "description": "The on-hand quantity at which the product should be reordered. Send null to clear it; omit it to leave it as it is.", "example": "199.99", "pattern": "^-?[0-9]+(\\.[0-9]+)?$" }, "store_product_selection_criteria": { "description": "Criteria used to select products whose inventory will be updated.", "allOf": [ { "$ref": "#/components/schemas/StoreProductSelectionCriteria" } ] } }, "description": "The products to update, and the reorder levels or on-hand quantity to write to them." }, "UpsertStoreProductInventoryResponse": { "type": "object", "properties": { "updated_count": { "type": "integer", "description": "How many products the request updated." } }, "description": "The outcome of an inventory update. The updated products are not returned.", "required": [ "updated_count" ] }, "VariableWeight": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the record." }, "created_at": { "type": "string", "description": "When the record was created.", "format": "date-time" }, "name": { "type": "string", "description": "Human-readable name for the tare container, such as \"Produce bag\"." }, "store_id": { "type": "string", "description": "ID of the store the variable weight belongs to. Variable weights are not shared between stores.", "pattern": "^[0-9]+$" }, "unit_of_measure": { "description": "Unit of measure the weight is expressed in, limited to the units the point of sale can weigh in.", "allOf": [ { "$ref": "#/components/schemas/VariableWeightUnit" } ] }, "updated_at": { "type": "string", "description": "When the record was last changed.", "format": "date-time" }, "value": { "type": "string", "description": "Weight of the tare container, as a decimal string in the unit of measure.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "example": "199.99" } }, "description": "The weight of a tare container a product is sold in, such as a produce bag. It is subtracted from the scale reading so the shopper pays for the contents rather than the packaging.", "required": [ "id", "created_at", "name", "store_id", "unit_of_measure", "updated_at", "value" ] }, "VariableWeightInUseError": { "type": "object", "properties": { "error_code": { "type": "string", "enum": [ "variable_weight_in_use" ] } }, "required": [ "error_code" ] }, "VariableWeightList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/VariableWeight" } }, "has_more": { "type": "boolean", "description": "Whether more records follow this page." } }, "required": [ "data", "has_more" ] }, "VariableWeightUnit": { "type": "string", "enum": [ "LBS", "OZ" ] } } } }