API Reference

Create a purchase order for a location (vendor by vendor_id or external_vendor_id).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:purchase_orders.
• Provide vendor_id (integer) or external_vendor_id (GUID); at least one is required.
• Processor also requires external_order_id and a non-empty items array.
• Each item requires: sku, product_name, unit, quantity (> 0), unit_price (>= 0). Optional: expiry_date (YYYY-MM-DD), category_name, product_description.
• payment_status: "Paid" or "Unpaid". expected_delivery_date: YYYY-MM-DD.

Request parameters

{
    "location_id": 72493,
    "vendor_id": 12,
    "external_order_id": "EXT-PO-2026-001",
    "expected_delivery_date": "2026-07-20",
    "payment_status": "Unpaid",
    "purchase_order_name": "Weekly produce",
    "comments": "Deliver to back dock",
    "shipping_address": "123 Main St, Austin, TX 78701",
    "items": [
        {
            "product_name": "Organic Tomatoes",
            "sku": "TOM-ORG-001",
            "unit": "Case",
            "quantity": 10,
            "unit_price": 24.5,
            "expiry_date": "2026-08-01"
        }
    ]
}

{
    "success": true,
    "data": {
        "purchase_order_id": 1842,
        "location_id": 72493,
        "vendor_id": 12,
        "external_order_id": "EXT-PO-2026-001",
        "received_status": "Open",
        "items_updated": 1
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update an open (non-received) purchase order and replace its line items.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:purchase_orders.
• purchase_order_id required (alias po_id accepted).
• vendor_id or external_vendor_id required.
• items required; each line needs sku and quantity > 0. Optional purchase_order_detail_id to map existing lines.
• Returns 404 if PO missing; 409 if status is Received (1).

Request parameters

{
    "location_id": 72493,
    "purchase_order_id": 1842,
    "vendor_id": 12,
    "external_order_id": "EXT-PO-2026-001",
    "expected_delivery_date": "2026-07-22",
    "payment_status": "Unpaid",
    "purchase_order_name": "Weekly produce (revised)",
    "comments": "Qty updated",
    "items": [
        {
            "sku": "TOM-ORG-001",
            "product_name": "Organic Tomatoes",
            "unit": "Case",
            "quantity": 12,
            "unit_price": 24.5
        }
    ]
}

{
    "success": true,
    "data": {
        "purchase_order_id": 1842,
        "location_id": 72493,
        "vendor_id": 12,
        "external_order_id": "EXT-PO-2026-001",
        "items_updated": 1,
        "amount": 294
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List purchase orders for a location by status, with optional filters and pagination.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:purchase_orders.
• status: 0 = Open, 1 = Received, 2 = Draft.
• Optional filters: vendor_id, product_id, start_date/end_date, expiry_start_date/expiry_end_date.
• Default page=1, per_page=20 (max 100).

Request parameters

{
    "location_id": 72493,
    "status": "0",
    "vendor_id": "3",
    "product_id": "139",
    "start_date": "2026-07-01",
    "end_date": "2026-07-31",
    "expiry_start_date": "2026-07-01",
    "expiry_end_date": "",
    "page": 1,
    "per_page": 10
}

{
    "success": true,
    "data": {
        "purchase_orders": [
            {
                "purchase_order_id": 1842,
                "vendor_id": 12,
                "status": 0,
                "po_name": "Weekly produce",
                "create_date": "2026-07-10 09:15:00",
                "expected_delivery_date": "2026-07-20",
                "receive_date": null,
                "payment_status": 0,
                "amount": 245,
                "line_items_amount": 245,
                "external_order_id": "EXT-PO-2026-001",
                "comment": "Deliver to back dock",
                "parent_purchase_order_id": 0,
                "received_products_count": 0,
                "total_po_product": 1,
                "vendor_name": "Fresh Farms LLC",
                "purchase_order_detail": [
                    {
                        "purchase_order_detail_id": 9011,
                        "product_id": 139,
                        "unit_id": 4,
                        "quantity": 10,
                        "balance_quantity": 10,
                        "cost_price": 24.5,
                        "status": 0,
                        "expiry_date": "2026-08-01",
                        "receive_date": null
                    }
                ]
            }
        ],
        "pagination": {
            "total": 1,
            "page": 1,
            "per_page": 10,
            "total_pages": 1
        }
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Get a single purchase order with line items.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:purchase_orders.
• purchase_order_id required (alias po_id accepted).

Request parameters

{
    "location_id": 72493,
    "purchase_order_id": 1842
}

{
    "success": true,
    "data": {
        "purchase_order": {
            "purchase_order_id": 1842,
            "vendor_id": 12,
            "status": 0,
            "po_name": "Weekly produce",
            "create_date": "2026-07-10 09:15:00",
            "expected_delivery_date": "2026-07-20",
            "receive_date": null,
            "payment_status": 0,
            "amount": 245,
            "line_items_amount": 245,
            "external_order_id": "EXT-PO-2026-001",
            "comment": "Deliver to back dock",
            "parent_purchase_order_id": 0,
            "received_products_count": 0,
            "total_po_product": 1,
            "vendor_name": "Fresh Farms LLC",
            "purchase_order_detail": [
                {
                    "purchase_order_detail_id": 9011,
                    "product_id": 139,
                    "unit_id": 4,
                    "quantity": 10,
                    "balance_quantity": 10,
                    "cost_price": 24.5,
                    "status": 0,
                    "expiry_date": "2026-08-01",
                    "receive_date": null
                }
            ]
        }
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Get payment status for a purchase order as Paid or Unpaid.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:purchase_orders.
• Maps DB payment_status == 2 to "Paid"; otherwise "Unpaid".

Request parameters

{
    "location_id": 72493,
    "purchase_order_id": 1842
}

{
    "success": true,
    "data": {
        "payment_status": "Unpaid"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update purchase order payment status.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:purchase_orders.
• payment_status must be "Paid" or "Unpaid".

Request parameters

{
    "location_id": 72493,
    "purchase_order_id": 1842,
    "payment_status": "Paid"
}

{
    "success": true,
    "data": {
        "success": true,
        "message": "Payment status updated successfully"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List products for a location (useful when assigning product_ids on discounts).

• Requires scope read:catalog.
• Optional category_id or product_id filters narrow the catalog list.
• include_all_products: omit or true for full catalog; false for ecommerce-enabled products only.
• Supports optional page / per_page (default per_page 20, max 100).
• Each product includes gallery: an array of {id, position, image} from product_images (empty array when none). Use id as image_id with delete-product-gallery-image.

Request parameters

{
    "location_id": 72493,
    "category_id": "1",
    "product_id": "139",
    "include_all_products": false,
    "per_page": 20,
    "page": 1
}

{
    "success": true,
    "data": {
        "products": [
            {
                "product_id": 6,
                "product_name": "2X Large",
                "description": "",
                "unit_id": 0,
                "selling_price": 0,
                "sku": "",
                "category_id": 2,
                "image": "https://s3.amazonaws.com/dev_server_bucket/avatar/[120x89]1979302841-1779963936.png",
                "total_modifiers": 0,
                "available_quantity": 0,
                "product_type": "Component",
                "for_sale": 0,
                "gallery": [
                    {
                        "id": 101,
                        "position": 1,
                        "image": "products/[400x400]72493_6_gallery1.jpg"
                    }
                ]
            },
            {
                "product_id": 7,
                "product_name": "3L Large ",
                "description": "",
                "unit_id": 0,
                "selling_price": 0,
                "sku": "",
                "category_id": 2,
                "image": "https://s3.amazonaws.com/dev_server_bucket/avatar/[120x89]1979302841-1779963936.png",
                "total_modifiers": 0,
                "available_quantity": 0,
                "product_type": "Component",
                "for_sale": 0,
                "gallery": []
            }
        ]
    },
    "timestamp": "2026-07-09T10:05:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create one or more products for a location (batch via products array).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• products must be a non-empty array (max 50). Each row requires product_name.
• Optional root source / employee_id are merged into every row.
• Per product: category_id or category_name (default "Default"); product_type product|service|component (or for_sale 0/1/2); unit_id or unit; tax_slab_id (else location default tax); selling_price, sku, barcode, description, image_url, etc.
• barcode is an array of UPC strings (e.g. ["111","222","333"]). First value is the primary barcode; all are stored on the product (same rules as the SalesVu portal). A single-string or comma/semicolon-separated string is also accepted for compatibility. Max count follows the location UPC limit (default 5). Duplicates in the list or UPCs already used by another product return validation errors.
• Optional image_url (http/https): after the product is created, SalesVu downloads the image, uploads it to product storage, and sets it as the product main image (same flow as Import Product Images). Invalid URL format fails the row before create. If download/upload fails after create, the product is still created and a warning is returned.
• For multi-location product management accounts, the product is created on the owner base store, linked to location_id in store_product_map, and synced — same behavior as SalesVuApi create_products / portal save. This is required for the product to show linked locations and open correctly in the portal edit screen.
• Product/service types require a valid tax slab at the location. Partial batch success returns created + failed arrays.

Request parameters

{
    "location_id": 72493,
    "source": "API_V1",
    "products": [
        {
            "product_name": "House Latte",
            "category_id": 12,
            "product_type": "product",
            "selling_price": 4.5,
            "sku": "LATTE-001",
            "barcode": [
                "111111111111",
                "222222222222"
            ],
            "unit": "Item",
            "description": "12oz latte",
            "image_url": "https://example.com/images/latte.jpg"
        }
    ]
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "products": [
            {
                "index": 0,
                "product_id": 1842,
                "sku": "LATTE-001",
                "image": "products/[400x400]72493_1842_...jpg"
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Partial-update a product by product_id (whitelist fields only).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• HTTP method PUT. Requires location_id and product_id; at least one updatable field.
• Updatable: product_name, product_short_name, description, selling_price, ecommerce_price, sku, category_id, unit_id, is_active, for_sale, online_status, price_type, barcode, image_url.
• barcode is an array of UPC strings (e.g. ["111","222","333"]). Replaces existing barcodes for the product. Empty array [] (or empty string) clears all barcodes. First value is primary. A single string or comma/semicolon-separated string is also accepted. Max count follows the location UPC limit (default 5).
• Optional image_url (http/https): downloads and sets the product main image (same flow as create-product). Can be sent alone or with other fields. JPEG/PNG/WebP only.
• Returns 404 if product not found; 400 if SKU already exists, barcode validation fails, or no updatable fields provided.

Request parameters

{
    "location_id": 72828,
    "product_id": 90,
    "product_name": "House Latte Large",
    "product_short_name": "House Latte",
    "description": "12oz latte",
    "category_id": 9,
    "selling_price": 5.5,
    "ecommerce_price": 3.5,
    "price_type": 1,
    "sku": "LATTE-001",
    "barcode": [
        "111111111111",
        "222222222222"
    ],
    "unit_id": 1,
    "is_active": 1,
    "image_url": "https://example.com/images/latte-main.jpg"
}

{
    "success": true,
    "data": {
        "product_id": 1842,
        "location_id": 72493,
        "updated_fields": [
            "product_name",
            "selling_price",
            "is_active",
            "barcode",
            "image_url"
        ],
        "image": "products/[400x400]72493_1842_...jpg",
        "warning": ""
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Upload gallery images for an existing product from public image URLs.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• Existing products only — does not create products.
• gallery is required. Each item needs image_url and position (1–10).
• If a gallery position already has an image, it is replaced. Maximum 10 gallery images per product.
• Supported image types: JPEG, PNG, WebP (same as portal Import Product Images).
• For multi-location accounts, gallery images are applied on the owner base store and synced across locations.
• Partial failures (e.g. one bad gallery URL) return success with warning when at least one image was saved.
• To set the product main image, use create-product image_url (or portal Import Product Images Main Image URL).

Request parameters

{
    "location_id": 72493,
    "product_id": 1842,
    "gallery": [
        {
            "image_url": "https://example.com/images/latte-1.jpg",
            "position": 1
        },
        {
            "image_url": "https://example.com/images/latte-2.jpg",
            "position": 2
        }
    ]
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "product_id": 1842,
        "gallery": [
            {
                "id": 1,
                "position": 1,
                "image": "products/[400x400]72493_1842_g1...jpg"
            },
            {
                "id": 2,
                "position": 2,
                "image": "products/[400x400]72493_1842_g2...jpg"
            }
        ],
        "warning": ""
    },
    "timestamp": "2026-08-05T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Delete one product gallery image by image_id (product_images.id).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• HTTP method DELETE. Requires location_id and image_id (from catalog products gallery[].id).
• Optional product_id validates that the image belongs to that product.
• Soft-deletes the row (deleted=1). For multi-location accounts, matching image_path is soft-deleted on other stores.

Request parameters

{
    "location_id": 72493,
    "image_id": 101,
    "product_id": 1842
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "product_id": 1842,
        "image_id": 101,
        "position": 1,
        "deleted": true
    },
    "timestamp": "2026-08-05T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List categories for a location (useful when assigning category_ids on discounts).

• Requires scope read:catalog.
• Send JSON body with Content-Type: application/json.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "categories": [
            {
                "category_id": "12",
                "category_name": "Breads"
            },
            {
                "category_id": "13",
                "category_name": "Burgers"
            }
        ]
    },
    "timestamp": "2026-07-09T10:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create (or revive) a top-level category by name for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• If category_name already exists, deleted is cleared and existing category_id is returned.

Request parameters

{
    "location_id": 72493,
    "category_name": "Beverages"
}

{
    "success": true,
    "data": {
        "category_id": 42,
        "location_id": 72493
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Rename a category by category_id.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• HTTP method PUT. Requires location_id, category_id, and category_name.

Request parameters

{
    "location_id": 72493,
    "category_id": 42,
    "category_name": "Hot Beverages"
}

{
    "success": true,
    "data": {
        "category_id": 42,
        "location_id": 72493
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Soft-delete a category (sets deleted = 1).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• HTTP method DELETE. Soft-delete only; does not remove child rows in this call.

Request parameters

{
    "location_id": 72493,
    "category_id": 42
}

{
    "success": true,
    "data": {
        "category_id": 42,
        "location_id": 72493
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List sub-categories for a parent category.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:catalog.
• Returns non-deleted categories where parent_id = category_id, ordered by category_name.

Request parameters

{
    "location_id": 72493,
    "category_id": 12
}

{
    "success": true,
    "data": {
        "sub_categories": [
            {
                "category_id": "51",
                "category_name": "Espresso Drinks"
            },
            {
                "category_id": "52",
                "category_name": "Teas"
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Add a sub-category under a parent category.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• Inserts category with parent_id = category_id.
• Response category_id is the parent category_id (not the new sub-category id).

Request parameters

{
    "location_id": 72493,
    "category_id": 12,
    "category_name": "Cold Brew"
}

{
    "success": true,
    "data": {
        "category_id": 12,
        "location_id": 72493
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Get modifier groups and items for a product.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:catalog.
• Uses Cart::getModifiers; each group includes nested modifier_items.

Request parameters

{
    "location_id": 72493,
    "product_id": 1842
}

{
    "success": true,
    "data": {
        "modifiers": [
            {
                "modifier_id": 3,
                "modifier_name": "Milk Options",
                "multiple": "1",
                "mandatory": "0",
                "merge": "0",
                "modifier_items": [
                    {
                        "modifier_item_id": 11,
                        "product_id": 90,
                        "product_name": "Oat Milk",
                        "unit_id": 1,
                        "quantity": 1,
                        "extra_cost": 0.75,
                        "default": 0,
                        "item_image": ""
                    }
                ]
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List units for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:catalog.
• Returns non-deleted units ordered by unit_name.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "units": [
            {
                "unit_id": "1",
                "unit_name": "Case"
            },
            {
                "unit_id": "2",
                "unit_name": "Item"
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create (or reuse) a unit by name for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• Delegates to Product::create_and_update_unit; returns unit_id.

Request parameters

{
    "location_id": 72493,
    "unit_name": "Dozen"
}

{
    "success": true,
    "data": {
        "unit_id": 8,
        "location_id": 72493
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Add a unit conversion (unit_id -> conversion_unit_id with multiplier).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• unit_multiplier must be > 0.

Request parameters

{
    "location_id": 72493,
    "unit_id": 1,
    "conversion_unit_id": 2,
    "unit_multiplier": 12
}

{
    "success": true,
    "data": {
        "unit_conversion": true
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List active tax slabs for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:catalog.
• Returns active, non-deleted sales_tax_slab rows plus TAX_INCLUDED_IN_PRICE setting.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "tax_included_in_price": 0,
        "tax_slabs": [
            {
                "tax_slab_id": 1,
                "tax_slab_name": "Sales Tax",
                "tax_rate": 8.25,
                "is_default": 1,
                "included_in_price": 0,
                "create_date": "2025-01-10 12:00:00"
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Add a tax slab for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• tax_type 0 = local tax (default); 1 = shipped/destination tax.
• For tax_type 1: dest_type required (1 State/Province, 2 City, 3 Zipcode); dest_details comma-separated values; tax_behaviour 1 Replace Local Tax, 2 Additional to Local Tax.
• tax_rate must be numeric and >= 0. Duplicate tax_slab_name returns 409.
• is_default 1 clears previous default slab. included_in_price comes from location setting TAX_INCLUDED_IN_PRICE.

Request parameters

{
    "location_id": 72493,
    "tax_slab_name": "City Tax",
    "tax_rate": 1.5,
    "tax_type": 0,
    "is_default": 0
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "tax_slab_id": 14,
        "tax_slab_name": "City Tax",
        "tax_rate": 1.5,
        "tax_type": 0,
        "is_default": 0,
        "included_in_price": 0
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update a tax slab by tax_slab_id.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• HTTP method PUT. Requires location_id, tax_slab_id, tax_slab_name, tax_rate.
• Optional tax_type / dest_type / dest_details / tax_behaviour follow the same shipped-tax rules as add-tax.

Request parameters

{
    "location_id": 72493,
    "tax_slab_id": 14,
    "tax_slab_name": "City Tax",
    "tax_rate": 1.75
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "tax_slab_id": 14,
        "tax_slab_name": "City Tax",
        "tax_rate": 1.75,
        "tax_type": 0,
        "tax_dest_type": 0,
        "tax_dest_details": "",
        "tax_behaviour": 0
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Soft-delete a tax slab (sets is_active = 0).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:catalog.
• HTTP method DELETE. Soft-deactivates the slab.

Request parameters

{
    "location_id": 72493,
    "tax_slab_id": 14
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "tax_slab_id": 14
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List inventory rows for a location with pagination.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:inventory.
• HTTP method POST. Default page=1, per_page=50 (max 200).
• Optional product_id / category_id filters are applied when present.

Request parameters

{
    "location_id": 72493,
    "page": 1,
    "per_page": 50
}

{
    "success": true,
    "data": {
        "inventory": [
            {
                "product_id": 441,
                "inventory_unit_id": 1,
                "product_unit_id": 1,
                "quantity": 100,
                "required_quantity": 10,
                "available_quantity": 90,
                "cost_price": 2.1,
                "threshold_quantity": 5,
                "product_name": "Latte",
                "sku": "LATTE-01",
                "category_id": 8,
                "category_name": "Beverages",
                "unit_name": "Each"
            }
        ],
        "pagination": {
            "total": 1,
            "page": 1,
            "per_page": 50,
            "total_pages": 1
        }
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Adjust inventory quantity by a delta (optional new cost price).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:inventory.
• HTTP method POST. changed_qty is added to current quantity; result must not be negative.
• Optional new_cost_price updates inventory.cost_price when numeric.
• Returns 404 if no inventory row exists for the product.

Request parameters

{
    "location_id": 72493,
    "product_id": 441,
    "changed_qty": -5,
    "new_cost_price": 2.25
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "product_id": 441,
        "quantity_before": 100,
        "quantity_after": 95,
        "changed_qty": -5,
        "required_quantity": 10,
        "available_quantity": 85
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Change the inventory unit for a product at a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:inventory.
• HTTP method POST. Uses Product::changeInventoryUnit (same as portal unit change).
• Returns 404 if no inventory row exists for the product.

Request parameters

{
    "location_id": 72493,
    "product_id": 441,
    "unit_id": 3
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "product_id": 441,
        "unit_id": 3
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List customers for a location with pagination.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:customers.
• HTTP method POST. page maps to chunk offset (default 1); per_page maps to limit (default 50).
• Response includes customerData, cardData, total, and curr_time from chunk_customer_list.

Request parameters

{
    "location_id": 72493,
    "page": 1,
    "per_page": 50
}

{
    "success": true,
    "data": {
        "success": true,
        "data": {
            "customer_id": "a7969dfb-3f9c-9c78-e8ee-4fef5b477a64",
            "first_name": "Stream",
            "last_name": "T.",
            "account_number": null,
            "email": "",
            "phone": "+1 312-766-6835",
            "address": "",
            "city": "",
            "state": "",
            "zip": null,
            "country": "",
            "created_at": null,
            "updated_at": null,
            "server_date": "2026-07-01 12:54:04",
            "deleted": "0",
            "cc_number": null
        },
        "timestamp": "2026-07-13T00:00:00+00:00"
    }
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create a customer (or match existing by email/phone) for a location owner.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:customers.
• HTTP method POST. Requires first_name, last_name, email, and phone.

Request parameters

{
    "location_id": 72493,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "5125550100"
}

{
    "success": true,
    "data": {
        "cust_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "action": "insert"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update an existing customer by customer_id.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:customers.
• HTTP method PUT. Schema requires customer_id and location_id; first_name, last_name, email, phone are optional when non-empty.

Request parameters

{
    "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "location_id": 72493,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "5125550101"
}

{
    "success": true,
    "data": {
        "cust_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "action": "update",
        "duplicate": 1
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Get one or more customers by customer_ids for a location owner.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:customers.
• HTTP method POST. customer_ids must be a non-empty array of customer IDs.
• Returns customer rows from Customer::getCustomers (default object/assoc query result).

Request parameters

{
    "location_id": 72493,
    "customer_ids": [
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
}

{
    "success": true,
    "data": [
        {
            "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "[email protected]",
            "phone": "5125550100",
            "deleted": 0
        }
    ],
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Fetch an open online cart order for a customer at a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:orders.
• HTTP method POST. Validates order belongs to online_customer_id and is open.

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 3717
}

{
    "success": true,
    "data": {
        "total_items": 1,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "dm_id": 3,
        "csa_id": 0,
        "note": "Leave at door",
        "partial_amount": 5.5,
        "order_details": [
            {
                "order_detail_id": 9001,
                "product_id": 441,
                "unit_id": 1,
                "quantity": 1,
                "product_name": "Latte",
                "selling_price": 5,
                "modifiers": [],
                "notes": [
                    {
                        "comment": "Extra hot"
                    }
                ]
            }
        ],
        "subtotal_amount": 5,
        "total_tax": 0.5,
        "total_discount": 0,
        "total_amount": 5.5
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create a new open online order (or resume existing open order) and optionally add line items.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. online_customer_id 1 = guest.
• order_details optional; each line typically needs product_id, unit_id, quantity; optional selling_price, modifiers, notes, runtime_discount.
• Optional pickup_datetime, external_customer_id, has_runtime_discount, skip_discount_calc.

Request parameters

{
    "location_id": 72493,
    "online_customer_id": 3717,
    "pickup_datetime": "2026-07-15 10:00:00",
    "order_details": [
        {
            "product_id": 441,
            "quantity": 1,
            "unit_id": 1,
            "notes": [
                {
                    "comment": "Extra hot"
                }
            ]
        }
    ]
}

{
    "success": true,
    "data": {
        "total_items": 1,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "partial_amount": 5.5,
        "order_details": [
            {
                "order_detail_id": 9001,
                "product_id": 441,
                "unit_id": 1,
                "quantity": 1,
                "product_name": "Latte",
                "selling_price": 5
            }
        ],
        "subtotal_amount": 5,
        "total_tax": 0.5,
        "total_amount": 5.5
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Add one or more products to an existing open online order.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. order_details array is required (product_id, unit_id, quantity; optional selling_price, modifiers, notes).

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 3717,
    "order_details": [
        {
            "product_id": 442,
            "selling_price": 3.5,
            "unit_id": 1,
            "quantity": 1,
            "notes": [
                {
                    "comment": "No sugar"
                }
            ]
        }
    ]
}

{
    "success": true,
    "data": {
        "total_items": 2,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "partial_amount": 9.35,
        "order_details": [
            {
                "order_detail_id": 9001,
                "product_id": 441,
                "quantity": 1,
                "product_name": "Latte",
                "selling_price": 5
            },
            {
                "order_detail_id": 9002,
                "product_id": 442,
                "quantity": 1,
                "product_name": "Muffin",
                "selling_price": 3.5
            }
        ],
        "subtotal_amount": 8.5,
        "total_tax": 0.85,
        "total_amount": 9.35
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update quantities for existing online order line(s).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. Each order_details row needs order_detail_id and quantity.

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 3717,
    "order_details": [
        {
            "order_detail_id": 9001,
            "quantity": 3
        }
    ]
}

{
    "success": true,
    "data": {
        "total_items": 3,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "partial_amount": 16.5,
        "order_details": [
            {
                "order_detail_id": 9001,
                "product_id": 441,
                "quantity": 3,
                "product_name": "Latte",
                "selling_price": 5
            }
        ],
        "subtotal_amount": 15,
        "total_tax": 1.5,
        "total_amount": 16.5
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Replace modifiers (and optional notes) on existing online order line(s).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. Lines need order_detail_id, product_id, modifiers; optional notes and quantity.
• modifier_items typically include modifier_item_id, modifier_item_unit_id, quantity, optional extra_cost.

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 3717,
    "order_details": [
        {
            "order_detail_id": 9001,
            "product_id": 441,
            "quantity": 1,
            "modifiers": [
                {
                    "modifier_id": 10,
                    "modifier_items": [
                        {
                            "modifier_item_id": 1,
                            "modifier_item_unit_id": 4,
                            "quantity": 1,
                            "extra_cost": 0.5
                        }
                    ]
                }
            ],
            "notes": [
                {
                    "comment": "No foam"
                }
            ]
        }
    ]
}

{
    "success": true,
    "data": {
        "total_items": 1,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "partial_amount": 6.05,
        "order_details": [
            {
                "order_detail_id": 9001,
                "product_id": 441,
                "quantity": 1,
                "product_name": "Latte",
                "selling_price": 5.5,
                "modifiers": [
                    {
                        "modifier_id": 10,
                        "modifier_items": [
                            {
                                "modifier_item_id": 1,
                                "quantity": 1,
                                "extra_cost": 0.5
                            }
                        ]
                    }
                ]
            }
        ],
        "subtotal_amount": 5.5,
        "total_tax": 0.55,
        "total_amount": 6.05
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create a new registered online customer.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. Returns customer profile fields.

Request parameters

{
    "location_id": 72493,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "5125550100"
}

{
    "success": true,
    "data": {
        "online_customer_id": 3717,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone": "5125550100"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Reassign a guest online order to a registered customer.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. old_customer must be 1 (guest); new_customer is the target registered customer.
• Does not return the cart; returns customer profile fields.

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 1,
    "old_customer": 1,
    "new_customer": 3717
}

{
    "success": true,
    "data": {
        "online_customer_id": 3717,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "[email protected]",
        "phone": "5125550100"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Set the order-level note on an open online cart order.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST.

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 3717,
    "note": "Leave at door"
}

{
    "success": true,
    "data": {
        "total_items": 1,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "note": "Leave at door",
        "partial_amount": 5.5,
        "order_details": [
            {
                "order_detail_id": 9001,
                "product_id": 441,
                "quantity": 1,
                "product_name": "Latte"
            }
        ],
        "total_amount": 5.5
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Remove line item(s) from an open online order by order_detail_id.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method DELETE. order_details entries need order_detail_id.

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 3717,
    "order_details": [
        {
            "order_detail_id": 9002
        }
    ]
}

{
    "success": true,
    "data": {
        "total_items": 1,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "partial_amount": 5.5,
        "order_details": [
            {
                "order_detail_id": 9001,
                "product_id": 441,
                "quantity": 1,
                "product_name": "Latte"
            }
        ],
        "total_amount": 5.5
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Delete an open online order and return cart state.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method DELETE.

Request parameters

{
    "location_id": 72493,
    "order_id": 66166,
    "online_customer_id": 3717
}

{
    "success": true,
    "data": {
        "total_items": 0,
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 0,
        "partial_amount": 0,
        "order_details": [],
        "total_amount": 0
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Complete an open online order (optionally with advance payment_info, other_payment_method_id, or tip).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. payment_info required when store oopo_id > 1 unless other_payment_method_id is provided; forbidden when oopo_id === 1.
• other_payment_method_id is a payment_option.id from get-payment-methods; mutually exclusive with payment_info.
• When present, payment_info requires amount, process_data, acq_ref_data, token, auth_code, status, tran_type, card_type, masked_account, ref_no; amount must equal partial_amount.
• Optional tip applied when > 0. Success returns online_customer_id, store_id, order_id, store_order_id.

Request parameters

{
    "location_id": 72493,
    "online_customer_id": 3717,
    "order_id": 66166,
    "tip": 2,
    "payment_method_id": 2
}

{
    "success": true,
    "data": {
        "online_customer_id": 3717,
        "store_id": 72493,
        "order_id": 66166,
        "store_order_id": 88901
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List user-defined payment options for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:orders.
• HTTP method POST. Returns payment_option rows where user_defined = 1 and status <> 2.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "status": "success",
        "data": [
            {
                "id": 1,
                "display_name": "Cash",
                "mode": "cash"
            },
            {
                "id": 2,
                "display_name": "Credit Card",
                "mode": "card"
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List valid POS payment device IDs for a store.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:orders.
• HTTP method POST.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "payment_devices": [
            "ONLINE",
            "RECURRING",
            "APPOINTMENT",
            "SalesVu.com",
            "SQUARE",
            "TRIP",
            "REFUND",
            "SHOPIFY",
            "POS-001",
            "SV_ADMIN_VY"
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Load a single store POS order by order_id and payment_device.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:orders.
• HTTP method POST. payment_device must be in the store payment-devices list.
• include_returns=1 includes deleted/return lines; include_customers=1 fills order.customer_info.

Request parameters

{
    "location_id": 72493,
    "order_id": 10582,
    "payment_device": "POS-001",
    "include_returns": 0,
    "include_customers": 1
}

{
    "success": true,
    "data": {
        "order_id": 10582,
        "pos_id": "POS-001",
        "order": {
            "order_id": 10582,
            "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "customer_info": {
                "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "first_name": "Jane",
                "last_name": "Doe",
                "email": "[email protected]",
                "phone": "5125550100"
            },
            "status": 1,
            "pos_id": "POS-001",
            "total_amount": 42.5,
            "subtotal_amount": 40,
            "total_tax": 2.5,
            "amount_due": 42.5,
            "total_items": 2,
            "order_details": [
                {
                    "order_detail_id": 9001,
                    "product_id": 441,
                    "unit_id": 1,
                    "quantity": 2,
                    "product_name": "Latte",
                    "sku": "LATTE-01",
                    "selling_price": 5,
                    "selling_price_wq": 10
                }
            ]
        }
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Complete a store POS order payment callback (card/MPS, Zapper, ECOM, or SV_ADMIN_VY).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:orders.
• HTTP method POST. Schema requires location_id, order_id, payment_device.
• Card path requires amount, token, process_data, acq_ref_data, auth_code, tran_type, card_type, masked_account, ref_no, status.
• When token is "no" (Zapper): requires status success|failed, initiated_by, pos_reference, numeric amount; optional tip.
• Success happy path returns msg "Information updated successfully".

Request parameters

{
    "location_id": 72493,
    "order_id": 10582,
    "payment_device": "POS-001",
    "amount": "42.50",
    "token": "tok_abc123",
    "process_data": "PDATA...",
    "acq_ref_data": "ACQ...",
    "auth_code": "A1B2C3",
    "status": "Approved",
    "tran_type": "Sale",
    "card_type": "VISA",
    "masked_account": "************1111",
    "ref_no": "REF998877"
}

{
    "success": true,
    "data": {
        "msg": "Information updated successfully"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

{
    "location_id": 72493,
    "order_id": 10582,
    "payment_device": "POS-001",
    "token": "no",
    "amount": "42.50",
    "tip": "2.00",
    "status": "success",
    "initiated_by": "ZAPPER",
    "pos_reference": "zap-ref-1001"
}

{
    "success": true,
    "data": {
        "msg": "Information updated successfully"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Return store orders for a date range (max 7 days), with optional returns and customers.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:orders.
• HTTP method POST. Dates are store-local calendar days (start 00:00:00 through end 23:59:00).
• End must be after start; range must be <= 7 days.
• Controller returns { data: [...] }; middleware nests under response data (data.data).

Request parameters

{
    "location_id": 72493,
    "start_date": "2026-07-06",
    "end_date": "2026-07-12",
    "include_returns": 0,
    "include_customers": 1
}

{
    "success": true,
    "data": {
        "data": [
            {
                "order_id": 10582,
                "pos_id": "POS-001",
                "order": {
                    "order_id": 10582,
                    "pos_id": "POS-001",
                    "sub_total": 40,
                    "total_tax": 2.5,
                    "total_amount": 42.5,
                    "tip": 0,
                    "status": "closed",
                    "deleted": 0,
                    "update_date": "2026-07-12 14:22:01",
                    "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "check_closed": "2026-07-12 19:22:01"
                },
                "customer_info": {
                    "customer_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "first_name": "Jane",
                    "last_name": "Doe",
                    "email": "[email protected]",
                    "phone": "5125550100"
                },
                "order_detail": [
                    {
                        "order_id": 10582,
                        "order_detail_id": 9001,
                        "product_id": 441,
                        "product_name": "Latte",
                        "quantity": 2,
                        "sku": "LATTE-01",
                        "selling_price": 5,
                        "selling_price_wq": 10
                    }
                ]
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List non-deleted vendors for a store.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:vendors.
• HTTP method POST. Only location_id is validated; page/per_page in explorer samples are unused by the controller.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "vendors": [
            {
                "vendor_id": 12,
                "first_name": "",
                "last_name": "",
                "is_active": 1,
                "vendor_name": "Fresh Farms Co",
                "contact_name": "Alex Rivera",
                "phone": "5125550199",
                "email": "[email protected]",
                "send_po": 1,
                "payment_terms_id": 1
            }
        ]
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Return one active, non-deleted vendor row for vendor_id.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:vendors.
• HTTP method POST. Filters deleted = 0/NULL and is_active = 1.

Request parameters

{
    "location_id": 72493,
    "vendor_id": 12
}

{
    "success": true,
    "data": {
        "vendor_id": 12,
        "vendor_name": "Fresh Farms Co",
        "contact_name": "Alex Rivera",
        "phone": "5125550199",
        "email": "[email protected]",
        "address": "400 Warehouse Rd",
        "city": "Austin",
        "state": "TX",
        "country": "US",
        "zipcode": "78702",
        "website": "https://freshfarms.example",
        "send_po": 1,
        "is_active": 1,
        "payment_terms_id": 1,
        "deleted": 0
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Get or create a vendor by name; returns the vendor ID.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:vendors.
• HTTP method POST. Existing vendor_name returns existing ID; otherwise inserts minimal vendor (is_active=1, payment_terms_id=1).
• data is a scalar vendor_id integer, not an object.

Request parameters

{
    "location_id": 72493,
    "vendor_name": "Fresh Farms Co"
}

{
    "success": true,
    "data": 12,
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update vendor name and optional contact fields.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:vendors.
• HTTP method PUT. Required: location_id, vendor_id, vendor_name.
• Optional: contact_name, phone, email, address, city, state, country, zipcode, website.
• Success returns vendor_id and vendor_name only.

Request parameters

{
    "location_id": 72493,
    "vendor_id": 12,
    "vendor_name": "Fresh Farms Co LLC",
    "contact_name": "Alex Rivera",
    "phone": "5125550199",
    "email": "[email protected]",
    "address": "400 Warehouse Rd",
    "city": "Austin",
    "state": "TX",
    "country": "US",
    "zipcode": "78702",
    "website": "https://freshfarms.example"
}

{
    "success": true,
    "data": {
        "vendor_id": 12,
        "vendor_name": "Fresh Farms Co LLC"
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Soft-clear then remap products to a vendor (by product IDs and/or category expansion).

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:vendors.
• HTTP method POST. Either product_ids or category_ids is required (product_ids may be [] to clear all mappings).
• Also accepts legacy assign_prods_to_vendor; categories via category_ids / assign_cats_to_vendor.
• Flow: soft-delete all vendor_product for vendor, then upsert selected products.

Request parameters

{
    "location_id": 72493,
    "vendor_id": 12,
    "product_ids": [
        441,
        442
    ],
    "category_ids": [
        8
    ]
}

{
    "success": true,
    "data": {
        "vendor_id": 12,
        "mapped_product_count": 5
    },
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List products assigned to a vendor.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:vendors.
• HTTP method POST. Returns product_id, quantity, cost_price, product_name, unit_id, unit_name.

Request parameters

{
    "location_id": 72493,
    "vendor_id": 12
}

{
    "success": true,
    "data": [
        {
            "product_id": 441,
            "quantity": 0,
            "cost_price": 2.1,
            "product_name": "Latte",
            "unit_id": 1,
            "unit_name": "Each"
        }
    ],
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Hard-delete one vendor_product row for vendor_id + product_id.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope write:vendors.
• HTTP method DELETE. Uses DELETE FROM vendor_product (not soft-delete).
• Vendor::delete_product_assign_to_vendor returns nothing; data is typically null on success.

Request parameters

{
    "location_id": 72493,
    "vendor_id": 12,
    "product_id": 441
}

{
    "success": true,
    "data": null,
    "timestamp": "2026-07-13T00:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List discounts for a location with pagination.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token that includes scope read:discounts.
• discount_level: 0 = product/category level, 1 = order level.
• operator: "%" = percent discount, "+" = fixed amount.

Request parameters

{
    "location_id": 66466,
    "page": 1,
    "per_page": 50
}

{
    "success": true,
    "data": {
        "location_id": 66466,
        "discounts": [
            {
                "discount_id": 1,
                "discount_name": "Test Discount",
                "discount_type_id": 1,
                "discount_type_name": "Non-Time",
                "discount_type": 0,
                "discount_amount": 10,
                "operator": "%",
                "coupon_code": "",
                "end_date": "",
                "discount_level": 1,
                "is_active": 1
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 50,
            "total": 1,
            "total_pages": 1
        }
    },
    "timestamp": "2026-07-09T09:03:26+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create a discount (non-time, time-based, coupon, or customer discount).

• Required at minimum: location_id, discount_name. Additional fields depend on discount_type / discount_type_id.
• discount_type 0 = percent, 1 = fixed amount (maps to Non-Time when discount_type_id omitted). Or send discount_type / discount_type_id: 1 Non-Time, 2 Time Based, 5 Coupon, 6 Customers.
• discount_operator: "%" or "+" (optional if discount_type 0/1 is used for percent/fixed).
• For time-based (type 2): send nested time_based object. Same field meanings as discounts/add-discount.php (timebased-discount.php).
• time_based.recurrence_action: 1 = enable recurrence (same as Recurrence toggle on web). Omit or empty = one-time date window only.
• time_based.end_type: 0 = End by date (requires end_recur_date), 1 = No end date, 2 = End after N occurrences (requires end_after_value). Maps to the web "end_date" radio.
• time_based.start_recur_date: required start date for type 2 (YYYY-MM-DD preferred; MM/DD/YYYY also accepted).
• time_based.recurrence_type: "daily" or "weekly" (used when recurrence_action is enabled).
• time_based.daily_recurrence: when recurrence_type is "daily" — 1 = Every Day(s), 2 = Every Weekday.
• time_based.daily_recurrence_day: when daily_recurrence is 1 — repeat every N days (1-999). Required when daily_recurrence is 1.
• discount_level 0 = product/category level (category_ids / product_ids); 1 = order level.
• discount_value with operator % must be greater than 0 and less than or equal to 100.

Request parameters

{
    "location_id": 66466,
    "discount_name": "API Happy Hour",
    "discount_type": 2,
    "discount_operator": "%",
    "discount_value": 15,
    "discount_level": 0,
    "coupon_start_date": "08/01/2026",
    "coupon_expiry_date": "08/31/2026",
    "max_usage": 100,
    "user_specified_code": "API101",
    "product_ids": [
        101
    ],
    "time_based": {
        "recurrence_action": 1,
        "end_type": 0,
        "start_recur_date": "2026-08-01",
        "end_recur_date": "2026-08-31",
        "recurrence_type": "daily",
        "daily_recurrence": 1,
        "daily_recurrence_day": 1,
        "discount_start_hrs": "16",
        "discount_start_min": "00",
        "discount_end_hrs": "18",
        "discount_end_min": "00"
    }
}

{
    "success": true,
    "data": {
        "location_id": 66466,
        "discount_id": 1,
        "discount_name": "API Happy Hour",
        "discount_type": 0,
        "discount_value": 15,
        "discount_amount": 15,
        "operator": "%",
        "discount_type_id": 2,
        "discount_level": 0
    },
    "timestamp": "2026-07-29T08:56:35+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update an existing discount by discount_id.

• Requires write:discounts scope.
• Same payload shape as create, plus required discount_id.
• For Time Based (type 2), send the same nested time_based fields documented on create (recurrence_action, end_type, start_recur_date, recurrence_type, daily_recurrence, daily_recurrence_day, etc.).
• Returns 404 if the discount is not found; 409 if a coupon is already used on receipts.

Request parameters

{
    "location_id": 66466,
    "discount_id": 1,
    "discount_name": "API Happy Hour",
    "discount_type": 2,
    "discount_operator": "%",
    "discount_value": 15,
    "discount_level": 0,
    "product_ids": [
        101
    ],
    "time_based": {
        "recurrence_action": 1,
        "end_type": 0,
        "start_recur_date": "2026-08-01",
        "end_recur_date": "2026-08-31",
        "recurrence_type": "daily",
        "daily_recurrence": 1,
        "daily_recurrence_day": 1,
        "discount_start_hrs": "16",
        "discount_start_min": "00",
        "discount_end_hrs": "18",
        "discount_end_min": "00"
    }
}

{
    "success": true,
    "data": {
        "location_id": 66466,
        "discount_id": 1,
        "discount_name": "API Happy Hour",
        "discount_type": 0,
        "discount_value": 15,
        "discount_amount": 15,
        "operator": "%",
        "discount_type_id": 2,
        "discount_level": 0
    },
    "timestamp": "2026-07-29T09:21:23+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Soft-delete a discount.

• Requires write:discounts scope.
• Returns 404 if not found; 409 if the coupon is linked to receipts and cannot be deleted.

Request parameters

{
    "location_id": "",
    "discount_id": 1
}

{
    "success": true,
    "data": {
        "location_id": 66466,
        "discount_id": 1,
        "deleted": true
    },
    "timestamp": "2026-07-09T10:47:51+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List locations (stores) for the connected account.

• Send JSON in the request body with Content-Type: application/json (body may be empty {}).
• Authorize with Bearer access token or account API key that includes scope read:store.
• Locations are resolved from the token owner_id (salesvu_web.store.ownerid). Do not pass owner_id in the request.
• Account API keys return all matching stores for the key owner. OAuth employee tokens return only stores assigned to that employee.
• HTTP method POST. Default status filter is active (store.status = 1). Pass status=all to include inactive locations.
• Use location_id from this response as location_id on other v1 endpoints (customers, catalog, inventory, etc.).

Request parameters

{
    "status": "active",
    "page": 1,
    "per_page": 100
}

{
    "success": true,
    "data": {
        "owner_id": 12345,
        "locations": [
            {
                "location_id": 72493,
                "name": "Downtown Cafe",
                "address": "123 Main St",
                "city": "Austin",
                "state": "TX",
                "zip": "78701",
                "country": "United States",
                "phone": "5125550100",
                "timezone": "America/Chicago",
                "latitude": 30.2672,
                "longitude": -97.7431,
                "online_ordering": 1,
                "status": "active"
            },
            {
                "location_id": 72510,
                "name": "Airport Kiosk",
                "address": "3600 Airport Blvd",
                "city": "Austin",
                "state": "TX",
                "zip": "78752",
                "country": "United States",
                "phone": "5125550199",
                "timezone": "America/Chicago",
                "latitude": 30.1975,
                "longitude": -97.6664,
                "online_ordering": 0,
                "status": "active"
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 100,
            "total": 2,
            "total_pages": 1
        }
    },
    "timestamp": "2026-07-13T14:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List general and specific industry categories for location creation.

• Send JSON in the request body with Content-Type: application/json (body may be empty {}).
• Authorize with Bearer access token or account API key that includes scope read:store.
• No location_id is required.
• Use general_industry_categories[].id as general_industry_category and specific_industry_categories[].id as specific_industry_category on POST /v1/locations/create.
• Optional general_industry_category (alias CLSICcategories) filters specific_industry_categories to that parent. General list is always returned in full.
• HTTP method POST.

Request parameters

{
    "general_industry_category": "1"
}

{
    "success": true,
    "data": {
        "general_industry_categories": [
            {
                "id": "1",
                "name": "Food & Drink"
            },
            {
                "id": "2",
                "name": "Retail"
            }
        ],
        "specific_industry_categories": [
            {
                "id": "1234",
                "name": "Coffee Shop",
                "general_industry_category": "1"
            },
            {
                "id": "1256",
                "name": "Restaurant",
                "general_industry_category": "1"
            }
        ]
    },
    "timestamp": "2026-08-03T08:15:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List countries available for location creation.

• Send JSON in the request body with Content-Type: application/json (body may be empty {}).
• Authorize with Bearer access token or account API key that includes scope read:store.
• No location_id is required.
• Use countries[].country_code as country_code on POST /v1/locations/create.
• HTTP method POST.

[]

{
    "success": true,
    "data": {
        "countries": [
            {
                "country_id": "95",
                "country_code": "US",
                "name": "United States"
            },
            {
                "country_id": "40",
                "country_code": "CA",
                "name": "Canada"
            }
        ]
    },
    "timestamp": "2026-08-03T10:50:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List states/provinces for a country.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope read:store.
• country_code is required (from /locations/countries; alias country_id also accepted).
• Use states[].state_code as state_code on POST /v1/locations/create when the country has states.
• Countries with no state rows return an empty states array; pass other_country_state (or free-text state_code) on create.
• HTTP method POST.

Request parameters

{
    "country_code": "US"
}

{
    "success": true,
    "data": {
        "country_id": "95",
        "country_code": "US",
        "country_name": "United States",
        "states": [
            {
                "state_code": "TX",
                "name": "Texas",
                "country_code": "US"
            },
            {
                "state_code": "CA",
                "name": "California",
                "country_code": "US"
            }
        ]
    },
    "timestamp": "2026-08-03T10:50:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

List available timezones for location creation.

• Send JSON in the request body with Content-Type: application/json (body may be empty {}).
• Authorize with Bearer access token or account API key that includes scope read:store.
• No location_id is required. Values match the create-location timezone dropdown (IANA identifiers).
• Use timezones[].timezone_id as timezone_id on POST /v1/locations/create. Only listed values are accepted.
• HTTP method POST.

[]

{
    "success": true,
    "data": {
        "timezones": [
            {
                "timezone_id": "America/Chicago",
                "name": "(GMT-06:00) America, Chicago"
            },
            {
                "timezone_id": "America/New_York",
                "name": "(GMT-05:00) America, New York"
            }
        ]
    },
    "timestamp": "2026-08-03T10:50:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Create a new location (store) for the connected account.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope create:store.
• Account owner is resolved from the token owner_id. Do not pass owner_id in the request.
• Call POST /v1/locations/industry-categories to retrieve valid general_industry_category and specific_industry_category ids.
• Call POST /v1/locations/countries, /locations/states, and /locations/timezones for valid country_code, state_code, and timezone_id.
• country_code must exist in /locations/countries. state_code must exist for countries that have states in /locations/states.
• timezone_id must be one of the available IANA values from /locations/timezones.
• For countries without state rows, pass other_country_state (or free-text state_code) for the province/region.
• Set no_website to skip website validation, or provide website / BusinessInfoWebsiteAddress.
• same_as_business_info defaults to Yes. When No, legal_* / LegalInfo* headquarter fields are required.

Request parameters

{
    "store_name": "Downtown Cafe",
    "address": "123 Main St",
    "city": "Austin",
    "state_code": "TX",
    "country_code": "US",
    "zip": "78701",
    "phone": "5125550100",
    "timezone_id": "America/Chicago",
    "same_as_business_info": "Yes",
    "business_description": "Cafe and light meals",
    "general_industry_category": "1",
    "specific_industry_category": "1234",
    "no_website": "no_website"
}

{
    "success": true,
    "data": {
        "message": "Location created successfully",
        "location_id": 72510,
        "location": {
            "location_id": 72510,
            "name": "Downtown Cafe",
            "address": "123 Main St",
            "city": "Austin",
            "state": "TX",
            "zip": "78701",
            "country": "United States",
            "phone": "5125550100",
            "timezone": "America/Chicago",
            "latitude": 0,
            "longitude": 0,
            "online_ordering": 0,
            "status": "active"
        }
    },
    "timestamp": "2026-07-31T12:57:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Partial update of a location (store) profile for the connected account.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope write:store.
• Only location_id is required. All other fields are optional and are applied only when present in the request.
• location_id must be accessible to the token (same access rules as other v1 endpoints).
• Accepts list-style field names (name, address, zip, timezone) or legacy names (storename, street_address, zipcode, timezone_name).
• When mobile_business=1 is sent, address/zip are cleared and service_zip_codes is required (existing value reused if omitted).
• timezone_display is ignored (UI only).
• Sending only location_id returns the current location with message "No fields to update."

Request parameters

{
    "location_id": 72493,
    "phone": "5125550100",
    "timezone": "America/Chicago"
}

{
    "success": true,
    "data": {
        "message": "Location profile has been updated successfully.",
        "location": {
            "location_id": 72493,
            "name": "Downtown Cafe",
            "address": "123 Main St",
            "city": "Austin",
            "state": "TX",
            "zip": "78701",
            "country": "United States",
            "phone": "5125550100",
            "timezone": "America/Chicago",
            "latitude": 30.2672,
            "longitude": -97.7431,
            "online_ordering": 1,
            "status": "active"
        },
        "mobile_business": 0,
        "service_zip_codes": ""
    },
    "timestamp": "2026-07-16T14:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Get the ecommerce out-of-stock setting for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope read:store.
• location_id is required and must be accessible to the token.
• Reads setting OUT_OF_STOCK_SETTING_ECOMMERCE from the location store DB (default 3).
• out_of_stock_settings lists allowed values: 1 = allow sales, 2 = show OOS banner and disable purchases, 3 = remove product.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "message": "Out of stock setting retrieved successfully.",
        "out_of_stock_setting_value": 3,
        "out_of_stock_settings": [
            {
                "label": "Allow sales to continue",
                "value": 1
            },
            {
                "label": "Show product with out of stock banner and disable purchases",
                "value": 2
            },
            {
                "label": "Remove product completely",
                "value": 3
            }
        ]
    },
    "timestamp": "2026-07-16T14:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Update the ecommerce out-of-stock setting for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope write:store.
• location_id is required and must be accessible to the token.
• Writes setting OUT_OF_STOCK_SETTING_ECOMMERCE in the location store DB.
• Allowed values: 1 = allow sales to continue, 2 = show out-of-stock banner and disable purchases, 3 = remove product completely.

Request parameters

{
    "location_id": 72493,
    "out_of_stock_setting": 2
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "message": "Out of stock setting updated successfully.",
        "out_of_stock_setting_value": 2
    },
    "timestamp": "2026-07-16T14:00:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Enable or disable online ordering for a location.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope write:store.
• location_id is required and must be accessible to the token.
• Writes setting ONLINE_ENABLE_DISABLE in the location store DB (0 = disable, 1 = enable).
• Optional display_message is saved to ONLINE_ENABLE_DISABLE_DISPLAY_MSG when provided and non-empty (shown on the shop page when ordering is disabled).

Request parameters

{
    "location_id": 72493,
    "status": 0
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "message": "Online ordering status updated successfully",
        "online_ordering_status": 0
    },
    "timestamp": "2026-07-17T06:30:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Get ecommerce preview URL or submit a store URL for Support review.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope write:store.
• location_id is required and must belong to the token owner_id.
• action is required: get_preview_url or get_published_url. Hyphenated values (get-preview-url) are accepted.
• Live publish (is_published=2) is not available via API — only Support admin can Activate on the portal.
• action=get_preview_url: ensures salesvu_web.templates_stores new_com row (insert/update language), then returns encrypted preview_url.
• action=get_published_url: submits store_url for support review (is_published=1 when pending). Emails support. Does not go live; portal Activate sets is_published=2. Requires connected Stripe for the location.
• publish_status is a string: pending (not submitted), submit for review (awaiting approval), published (approved/live by Support).
• store_url is required for action=get_published_url (subdomain slug or full host; aliases: website_url, publish_url, subdomain).
• language defaults to en (or existing template language for get_preview_url).

Request parameters

{
    "location_id": 72493,
    "action": "get_published_url",
    "store_url": "downtown-cafe",
    "language": "en"
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "action": "get_published_url",
        "published_url": "https://downtown-cafe.localstores.ai",
        "preview_url": "https://preview.localstores.ai?params=ENCRYPTED_PARAMS",
        "language": "en",
        "publish_status": "submit for review",
        "message": "Your website is now under review by our support team. You will receive an email when it is approved and published."
    },
    "timestamp": "2026-08-06T11:05:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.

Permanently delete a location (store) for the connected account.

• Send JSON in the request body with Content-Type: application/json.
• Authorize with Bearer access token or account API key that includes scope delete:store.
• location_id is required and must belong to the token owner_id.
• This action is irreversible: related salesvu_web records are removed and the store database salesvu_store_{location_id} is dropped.
• Also soft-deletes recurring_billing for the store and marks module_access.deleted=1 (same sequence as admin/clean-up-delete.php action=store).
• Use only on disposable/test locations unless you intend to remove production data.

Request parameters

{
    "location_id": 72493
}

{
    "success": true,
    "data": {
        "location_id": 72493,
        "store_name": "Downtown Cafe",
        "deleted": true,
        "message": "Store deleted successfully."
    },
    "timestamp": "2026-07-31T14:05:00+00:00"
}

Try this endpoint in the API Explorer with your OAuth token or account API key.