openapi: 3.2.0 info: title: Bevz Integrator Service Store Products API contact: name: API Support email: tech@bevz.com description: '# Introduction Welcome to the Bevz Integrator Service API documentation. The Bevz Integrator Service empowers our partners—including integrators and third-party POS providers—to seamlessly manage stores and related operations through a secure, scalable, and high-performance REST API platform. ## Who is this documentation for? This documentation is designed for integrators and third-party POS systems looking to leverage the Bevz SaaS platform to automate and streamline store management, menu operations, and more. ## Key Features By integrating with the Bevz platform, you gain access to: - **Rapid Store Onboarding:** Effortlessly provision and deprovision stores using our dedicated APIs. - **Menu Management:** Upload, update, and synchronize store menus programmatically. - **User & Access Management:** Manage integrator admin users and developer access for your organization. - **Order Processing:** Receive and process orders in real time via webhooks and API endpoints. - **Reporting & Analytics:** (Coming Soon) Access comprehensive reporting tools to monitor and optimize your operations. Explore the following sections to get started, review API endpoints, and discover best practices for a successful integration with Bevz. ' version: 1.12.0 servers: - url: https://api.bevz.com/integrator-service description: Production server - url: https://sandbox-api.bevz.com/integrator-service description: Sandbox server tags: - name: Store Products description: Store Products refer to inventory items that are available in a specific store. These products can be managed, updated, and retrieved through the Store Products API. paths: /integrators/{integrator_id}/stores/{store_id}/products: get: tags: - Store Products operationId: getProducts summary: Get Store Products description: "Retrieve a list of products available for sale in a specific store.\n\nUse this endpoint to fetch the current product catalog for a store, including inventory, pricing, and categorization details. \nYou can filter products by category, limit the number of results, and paginate through large catalogs.\n\n#### Example Usage\n\n- Retrieve all products in the \"Liquor\" category for a store.\n- Paginate through a large product catalog using the `limit` and `next_page` parameters.\n\nFor details on the product object schema, see [Store Products](#tag/models/Store-Products).\n" parameters: - name: integrator_id in: path required: true schema: type: integer format: int64 description: Unique identifier for the integrator. - name: store_id in: path required: true schema: type: string format: uuid description: Unique identifier for the store. - name: categoryL1 in: query required: false schema: type: string example: Liquor description: Filter products by top-level category (e.g., "Liquor"). - name: categoryL2 in: query required: false schema: type: string example: Rum description: Filter products by second-level category (e.g., "Rum"). - name: limit in: query required: false schema: type: integer example: 10 description: Maximum number of products to return per page. - name: next_page in: query required: false schema: type: string example: fb867d3b-d41f-4aaf-8b70-a7ffc7614ea0 description: Token for fetching the next page of results. - name: Authorization in: header description: JWT token for authenticating API requests. example: Bearer yourJWTtoken required: true schema: type: string responses: '200': description: Retrieved Store products content: application/json: schema: type: object properties: next_page: type: string example: fb867d3b-d41f-4aaf-8b70-a7ffc7614ea0 description: Token for fetching the next page of results, if more products are available. data: type: array description: List of product objects for the store. items: type: object properties: quantity: type: string example: Single description: The quantity or packaging unit of the product (e.g., Single, 6 Pack). size: type: string example: 375.00 ML Glass Bottle description: The size and packaging type of the product. upc: type: string example: 082000003809 description: Universal Product Code (UPC) for the product. categoryL1: type: string example: Liquor description: Top-level product category (e.g., Liquor, Beer, Wine). categoryL2: type: string example: Rum description: Second-level product category (e.g., Rum, Vodka). createdAt: type: string example: '2024-06-24T01:56:49.901Z' description: ISO 8601 timestamp when the product was created in the system. storeId: type: string example: 80c7b843-bb32-4eda-acb8-bd39a6826561 description: Unique identifier for the store this product belongs to. name: type: string example: Captain Morgan White Rum description: Display name of the product. isAvailableOnDoorDash: type: boolean example: true description: Indicates if the product is available for sale on DoorDash. stockCount: type: integer example: 1 description: Number of units of this product currently in stock. updatedAt: type: string example: '2024-06-24T01:56:49.901Z' description: ISO 8601 timestamp when the product was last updated. images: type: array example: [] description: List of image URLs or image objects associated with the product. forSale: type: boolean example: true description: Indicates if the product is currently available for sale. inStorePrice: type: integer example: 7.99 description: In-store price of the product (in dollars). merchantSuppliedId: type: string example: '72518102101' description: Identifier for the product as supplied by the merchant. productId: type: string example: 3f67bb88-b89e-4359-8b84-edfef9950b16 description: Unique identifier for the product in the system. prices: type: object description: Object containing delivery service-specific prices for the product. properties: doordashPrice: type: integer example: 8.99 description: Price of the product on DoorDash (in dollars). uberEatsPrice: type: integer example: 0 description: Price of the product on Uber Eats (in dollars). grubhubPrice: type: integer example: 0 description: Price of the product on Grubhub (in dollars). '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string errors: type: array examples: Integrator unauthorized to perform this action!: value: message: Unauthorized request! Please check your permission. errors: - Integrator unauthorized to perform this action! '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string example: User is not authorized to access this resource with an explicit deny /integrators/{integrator_id}/stores/{store_id}/products/{product_id}: parameters: - name: integrator_id in: path required: true schema: type: integer format: int64 description: Unique identifier for the integrator. - name: store_id in: path required: true schema: type: string format: uuid description: Unique identifier for the store. - name: product_id in: path required: true schema: type: string format: uuid description: Unique identifier for the product within the store. - name: Authorization in: header description: "JWT token for authenticating API requests. \n" example: Bearer yourJWTtoken required: true schema: type: string patch: tags: - Store Products operationId: patchProduct summary: Update Store Product description: 'Update the details of a specific product in a store. Use this endpoint to modify product attributes such as price, stock count, sale status, display name, or merchant-supplied ID. Only the fields provided in the request body will be updated; all other fields will remain unchanged. Typical use cases include: - Adjusting inventory levels after a sale or restock. - Updating the product''s in-store price. - Changing the product''s display name or marking it as unavailable for sale. ' requestBody: description: 'JSON payload specifying the product fields to update. Only include the fields you wish to modify. ' content: application/json: schema: type: object properties: inStorePrice: type: number format: float description: Updated in-store price for the product. example: 8.99 stockCount: type: number description: Updated inventory count for the product. example: 5 forSale: type: boolean description: 'Set to `false` to mark the product as unavailable for sale. ' example: false name: type: string description: Updated display name for the product. example: Product Test Name merchantSuppliedId: type: string description: Optional merchant-supplied identifier (e.g., SKU or barcode). example: '72518102101' responses: '200': description: Successfully updated store product content: application/json: schema: type: object properties: message: type: string example: Successfuly updated store product '400': description: Bad request! Please check your input. content: application/json: schema: type: object properties: message: type: string errors: type: array examples: Product ID is not found under this store: value: message: Bad request! Please check your input. errors: - Product ID is not found under this store. stockCount must be greater than or equal to 0: value: message: Bad request! Please check your input. errors: - '"stockCount" must be greater than or equal to 0' inStorePrice must be a positive number: value: message: Bad request! Please check your input. errors: - '"inStorePrice" must be a positive number' '"randomfield" is not allowed': value: message: Bad request! Please check your input. errors: - '"randomfield" is not allowed' '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string errors: type: array examples: Integrator unauthorized to perform this action!: value: message: Unauthorized request! Please check your permission. errors: - Integrator unauthorized to perform this action! '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string example: User is not authorized to access this resource with an explicit deny delete: tags: - Store Products operationId: deleteProduct summary: Delete Store Product description: 'Use this endpoint to remove a specific product from a store''s catalog. ' responses: '200': description: Successfully deleted store product content: application/json: schema: type: object properties: message: type: string example: Successfully deleted store product '400': description: Bad request! Please check your input. content: application/json: schema: type: object properties: message: type: string errors: type: array examples: Unable to delete item, store product does not exist: value: message: Bad request! Please check your input. errors: - Unable to delete item, store product does not exist '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string errors: type: array examples: Integrator unauthorized to perform this action!: value: message: Unauthorized request! Please check your permission. errors: - Integrator unauthorized to perform this action! '403': description: Forbidden content: application/json: schema: type: object properties: message: type: string example: User is not authorized to access this resource with an explicit deny x-tagGroups: - name: getting started tags: - Introduction - What is this documentation for? - Getting Started - name: guides tags: - Preparing Your Store - Using Webhooks - Uploading store menu - Receiving and processing order - name: apis tags: - Integrators - integrator_users - Stores - Store Products - Lotto Scratcher Games - Order - name: Delivery Services Onboarding tags: - Pick a Delivery Service for Onboarding API - Uber Eats Onboarding API Workflow - name: webhooks tags: - Webhooks - name: models tags: - models - name: faqs tags: - faq - name: changelog tags: - Changelog