swagger.yaml

openapi: 3.0.1
info:
  title: The Open Food Network
  description: Some endpoints are public and require no authorization; others require authorization. Talk to us to get your credentials set up. Check out our repo! https://github.com/openfoodfoundation/openfoodnetwork
  version: '0.1'
servers:
  - url: 'https://staging.katuma.org/api'
tags:
  - name: products
    description: Product endpoints
  - name: product variants
    description: Product variant endpoints
  - name: product images
    description: Product images endpoints
  - name: orders
    description: Order endpoints
  - name: shipments
    description: Order shipments endpoints
  - name: enterprises
    description: Enterprises endpoints
  - name: taxonomies
    description: Taxonomies endpoints
  - name: cookies_consent
    description: Cookies_Consent endpoints

security:
  - api_key: []

paths:
  /products/bulk_products:
    get:
      description: Gets all Products.
      tags:
        - products
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  pages:
                    type: integer
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'

  /products/overridable:
    get:
      description: Gets all Products.
      tags:
        - products
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  pages:
                    type: integer
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'

  /products:
    post:
      description: Posts a new Product.
      tags:
        - products
      parameters:
        - in: path
          name: product_object
          schema:
            type: object
            properties:
              product:
                $ref: '#/components/schemas/Product'
          required: true
          description: JSON object representing the Product to be posted.
      responses:
        '201':
          description: successful post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

  /products/{product_id}:
    get:
      description: Gets a Product by ID.
      tags:
        - products
      parameters:
        - in: path
          name: product_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Product.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    put:
      description: Updates the Product with the given ID.
      tags:
        - products
      parameters:
          - in: path
            name: product_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Product.
          - in: path
            name: product_object
            schema:
              type: object
              properties:
                product:
                  $ref: '#/components/schemas/Product'
            required: true
            description: JSON object representing the Product attributes to be overwritten.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
    delete:
      description: Deletes the Product with the given ID.
      tags:
        - products
      parameters:
          - in: path
            name: product_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Product.
      responses:
        '204':
          description: successful deletion

  /products/{product_id}/clone:
    post:
      description: Clones a Product by ID.
      tags:
        - products
      parameters:
        - in: path
          name: product_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Product to clone.
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'

  /products/{product_id}/variants:
    get:
      description: Gets all Variants of the given Product.
      tags:
        - product variants
      parameters:
        - in: path
          name: product_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Product.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  total_count:
                    type: integer
                  variants:
                    type: array
                    items:
                      $ref: '#/components/schemas/Variant'
                  pages:
                    type: integer
                  current_page:
                    type: integer
    post:
      description: Posts a new Product Variant.
      tags:
        - product variants
      parameters:
        - in: path
          name: product_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Product.
        - in: path
          name: variant_object
          schema:
            type: object
            properties:
              variant:
                $ref: '#/components/schemas/Variant'
          required: true
          description: JSON object representing the Variant to be posted.
      responses:
        '201':
          description: successful post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variant'

  /products/{product_id}/variants/{variant_id}:
    get:
      description: Gets a Variant by ID.
      tags:
        - product variants
      parameters:
        - in: path
          name: product_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Product.
        - in: path
          name: variant_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Variant.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variant'
    put:
      description: Updates the Variant with the given ID.
      tags:
        - product variants
      parameters:
          - in: path
            name: product_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Product.
          - in: path
            name: variant_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Variant.
          - in: path
            name: variant_object
            schema:
              type: object
              properties:
                variant:
                  $ref: '#/components/schemas/Variant'
            required: true
            description: JSON object representing the Variant attributes to be overwritten.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variant'
    delete:
      description: Deletes the Variant with the given ID.
      tags:
        - product variants
      parameters:
          - in: path
            name: product_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Product.
          - in: path
            name: variant_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Variant.
      responses:
        '204':
          description: successful deletion

  /product_images/{product_id}:
    post:
      description: Creates or updates product image.
      tags:
        - product images
      parameters:
          - in: path
            name: product_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Product.
      responses:
        '201':
          description: Product image added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductImage'
        '200':
          description: Product image updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductImage'

  /orders:
    get:
      description: Gets all Orders.
      tags:
        - orders
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order_Concise'
                  pagination:
                    type: string

  /orders/{order_number}/shipments.json:
    post:
      description: Creates a new Shipment and adds given variant.
      tags:
        - shipments
      parameters:
          - in: path
            name: order_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Order being changed.
          - in: path
            name: variant_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Variant to be added to the shipment.
          - in: path
            name: quantity
            schema:
              type: integer
            required: true
            description: Quantity of the variant to be added to the shipment.
          - in: path
            name: stock_location_id
            schema:
              type: integer
            required: true
            description: Stock location ID to be used to source the variant (for each OFN there's only one valid ID to be used here).
      responses:
        '201':
          description: Shipment successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'

  /orders/{order_number}/shipments/{shipment_number}.json:
    put:
      description: Updates shipment.
      tags:
        - shipments
      parameters:
          - in: path
            name: order_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Order being changed.
          - in: path
            name: shipment_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Shipment being changed.
          - in: path
            name: shipment_object
            schema:
              type: object
              properties:
                product:
                  $ref: '#/components/schemas/Shipment'
            required: true
            description: JSON object representing the Shipmeent attributes to be overwritten.
      responses:
        '200':
          description: Successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'

  /orders/{order_number}/shipments/{shipment_number}/add.json:
    put:
      description: Adds a variant quantity to the given shipment.
      tags:
        - shipments
      parameters:
          - in: path
            name: order_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Order being changed.
          - in: path
            name: shipment_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Shipment being changed.
          - in: path
            name: variant_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Variant to be added to the shipment.
          - in: path
            name: quantity
            schema:
              type: integer
            required: true
            description: Quantity of the variant to be added to the shipment.
      responses:
        '200':
          description: Variant quantity successfully added.

  /orders/{order_number}/shipments/{shipment_number}/remove.json:
    put:
      description: Removes a variant from the given shipment.
      tags:
        - shipments
      parameters:
          - in: path
            name: order_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Order being changed.
          - in: path
            name: shipment_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Shipment being changed.
          - in: path
            name: variant_id
            schema:
              type: integer
            required: true
            description: Numeric ID of the Variant to be removed from the shipment.
          - in: path
            name: quantity
            schema:
              type: integer
            required: true
            description: Quantity of the variant to be removed from the shipment.
      responses:
        '200':
          description: Variant quantity successfully rmeoved.

  /orders/{order_number}/shipments/{shipment_number}/ready.json:
    put:
      description: Moves the shipment to the ready state.
      tags:
        - shipments
      parameters:
          - in: path
            name: order_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Order being changed.
          - in: path
            name: shipment_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Shipment being changed.
      responses:
        '200':
          description: Successful workflow change.

  /orders/{order_number}/shipments/{shipment_number}/ship.json:
    put:
      description: Moves the shipment to the shipped state.
      tags:
        - shipments
      parameters:
          - in: path
            name: order_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Order being changed.
          - in: path
            name: shipment_number
            schema:
              type: integer
            required: true
            description: Number (not id) of the Shipment being changed.
      responses:
        '200':
          description: Successful workflow change.

  /enterprises:
    post:
      description: Creates a new Enterprise.
      tags:
        - enterprises
      parameters:
          - in: path
            name: enterprise_object
            schema:
              type: object
              properties:
                variant:
                  $ref: '#/components/schemas/Enterprise'
            required: true
            description: JSON object representing the Enterprise attributes to be created.
      responses:
        '201':
          description: Enterprise successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enterprise'
    put:
      description: Updates an Enterprise.
      tags:
        - enterprises
      parameters:
          - in: path
            name: enterprise_object
            schema:
              type: object
              properties:
                variant:
                  $ref: '#/components/schemas/Enterprise'
            required: true
            description: JSON object representing the Enterprise to be overwritten.
      responses:
        '200':
          description: Enterprise successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enterprise'

  /enterprises/{enterprise_id}/shopfront:
    get:
      description: Fetch Enterprise shopfront details (products not included).
      tags:
        - enterprises
      parameters:
          - in: path
            name: enterprise_id
            schema:
              type: integer
            required: true
            description: ID of the enterprise.
      responses:
        '200':
          description: Enterprise shopfront details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnterpriseShopfront'

  /enterprises/{enterprise_id}/update_image:
    post:
      description: Update enterprise images, promo and logo.
      tags:
        - enterprises
      parameters:
          - in: path
            name: enterprise_id
            schema:
              type: integer
            required: true
            description: ID of the enterprise.
          - in: path
            name: logo
            schema:
              type: string
              format: binary
            required: true
            description: Binary of the logo image.
          - in: path
            name: promo
            schema:
              type: string
              format: binary
            required: true
            description: Binary of the promo image.
      responses:
        '200':
          description: Image successfully uploaded. URL to the uploaded image
          content:
            application/json:
              schema:
                type: string

  /enterprises/{enterprise_permalink}/logo.json:
    delete:
      description: Delete enterprise logo image.
      tags:
        - enterprises
      parameters:
          - in: path
            name: enterprise_permalink
            schema:
              type: string
            required: true
            description: Permalink of the enterprise.
      responses:
        '200':
          description: Image successfully deleted. Json object representing the enterprise
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enterprise'

  /enterprises/{enterprise_permalink}/promo_image.json:
    delete:
      description: Delete enterprise promo image.
      tags:
        - enterprises
      parameters:
          - in: path
            name: enterprise_permalink
            schema:
              type: string
            required: true
            description: Permalink of the enterprise.
      responses:
        '200':
          description: Image successfully deleted. Json object representing the enterprise
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enterprise'

  /customers.json:
    get:
      description: List of customer objects for the current user (a customer connects a user with an enterprise)
      tags:
        - users
      responses:
        '200':
          description: List of Customer objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'

  /customers/{customer_id}.json:
    put:
      description: Updates customer object of current user (a customer connects a user with an enterprise)
      tags:
        - users
      parameters:
          - in: path
            name: customer_id
            schema:
              type: integer
            required: true
            description: ID of the customer object to update.
          - in: path
            name: customer_object
            schema:
              $ref: '#/components/schemas/Customer'
            required: true
            description: Customer object to be saved.
      responses:
        '200':
          description: Customer object saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'

  /enterprise_fees/{enterprise_fee_id}:
    delete:
      description: Deletes enterprise fee.
      tags:
        - enterprises
      parameters:
          - in: path
            name: enterprise_fee_id
            schema:
              type: integer
            required: true
            description: ID of the enterprise fee to delete.
      responses:
        '204':
          description: Enterprise fee successfully deleted.

  /taxonomies/{taxonomy_id}/taxons/:
    get:
      description: Gets all Taxons belonging to a given Taxonomy.
      tags:
        - taxonomies
      parameters:
        - in: path
          name: taxonomy_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxonomy.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Taxon'
    post:
      description: Posts a new Taxon to a given Taxonomy.
      tags:
        - taxonomies
      parameters:
        - in: path
          name: taxonomy_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxonomy.
        - in: path
          name: taxon_object
          schema:
            type: object
            properties:
              taxon:
                $ref: '#/components/schemas/Taxon'
          required: true
          description: JSON object representing the Taxon to be posted.
      responses:
        '201':
          description: successful post
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Taxon'

  /taxonomies/{taxonomy_id}/taxons/{taxon_id}:
    put:
      description: Updates the Taxon with the given Taxon ID in the Taxonomy with the given Taxonomy ID.
      tags:
        - taxonomies
      parameters:
        - in: path
          name: taxonomy_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxonomy.
        - in: path
          name: taxon_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxon.
        - in: path
          name: taxon_object
          schema:
            type: object
            properties:
              taxon:
                $ref: '#/components/schemas/Taxon'
          required: true
          description: JSON object representing the Taxon attributes to be overwritten.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Taxon'
    delete:
      description: Deletes the Taxon with the given Taxon ID from the Taxonomy with the given Taxonomy ID.
      tags:
        - taxonomies
      parameters:
        - in: path
          name: taxonomy_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxonomy.
        - in: path
          name: taxon_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxon.
      responses:
        '204':
          description: successful deletion

  /taxonomies/{taxonomy_id}/jstree:
    get:
      description: Gets a Taxonomy by ID with a jstree representation.
      tags:
        - taxonomies
      parameters:
        - in: path
          name: taxonomy_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxonomy.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonJstree'

  /taxonomies/{taxonomy_id}/taxons/{taxon_id}/jstree:
    get:
      description: Gest a given Taxon from given Taxonomy ID in the jstree representation.
      tags:
        - taxonomies
      parameters:
        - in: path
          name: taxonomy_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxonomy.
        - in: path
          name: taxon_id
          schema:
            type: integer
          required: true
          description: Numeric ID of the Taxon.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonJstree'

  /cookies/consent:
    get:
      description: Gets the client's Cookies_Consent status.
      tags:
        - cookies_consent
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cookies_Consent'
    post:
      description: Changes the client's Cookies-Consent status to true.
      tags:
        - cookies_consent
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cookies_Consent'
    delete:
      description: Changes the client's Cookies-Consent status to false.
      tags:
        - cookies_consent
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cookies_Consent'

components:
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Spree-Token
      in: header
  schemas:
    Pagination:
      type: object
      properties:
        results:
          type: integer
        pages:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
    Product:
      type: object
      properties:
        id: 
          type: integer
        name: 
          type: string
        sku:
          type: string
        price: 
          type: string
        available_on: 
          type: string
        permalink_live:
          type: string
        on_hand:
          type: integer
        variant_unit:
          type: string
        variant_unit_scale:
          type: string
        variant_unit_name:
          type: string
        tax_category_id:
          type: integer
        import_date:
          type: string
        image_url:
          type: string
        thumb_url:
          type: string
        producer_id:
          type: integer
        category_id:
          type: integer
        master:
          $ref: '#/components/schemas/AdminVariant'
        variants:
          type: array
          items:
            $ref: '#/components/schemas/AdminVariant'

    AdminVariant:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        on_hand:
          type: integer
        sku:
          type: string
        price: 
          type: string
        producer_name:
          type: string
        import_date:
          type: string
        options_text:
          type: string
        unit_value:
          type: integer
        unit_description:
          type: string
        unit_to_display:
          type: string
        display_as:
          type: string
        display_name:
          type: string
        name_to_display:
          type: string
        on_demand:
          type: boolean
        in_stock:
          type: boolean
        image:
          type: string
        variant_overrides:
          type: array
          items:
            $ref: '#/components/schemas/AdminVariantOverride'

    AdminVariantOverride:
      type: object
      properties:
        id:
          type: integer
        count_on_hand:
          type: integer
        default_stock:
          type: integer
        hub_id:
          type: integer
        import_date:
          type: string
        on_demand:
          type: boolean
        permission_revoked_at:
          type: string
        price:
          type: string
        resettable:
          type: boolean
        sku:
          type: string
        variant_id:
          type: integer

    Variant:
      type: object
      properties:
        id:
          type: integer
        on_hand:
          type: integer
        sku:
          type: string
        price:
          type: string
        product_name:
          type: string
        is_master:
          type: boolean
        options_text:
          type: string
        unit_value:
          type: integer
        unit_description:
          type: string
        unit_to_display:
          type: string
        display_as:
          type: string
        display_name:
          type: string
        name_to_display:
          type: string
        on_demand:
          type: boolean
        fees:
          type: object
        price_with_fees:
          type: string
        tag_list:
          type: array
          items:
            type: string

    ProductImage:
      type: object
      properties:
        id:
          type: integer
        alt:
          type: string
        thumb_url:
          type: string
        small_url:
          type: string
        image_url:
          type: string
        large_url:
          type: string

    Order_Concise:
      type: object
      properties:
        id:
          type: integer
        number:
          type: string
        full_name:
          type: string
        email:
          type: string
        phone:
          type: string
        completed_at:
          type: string
        display_total:
          type: string
        show_path:
          type: string
        edit_path:
          type: string
        state:
          type: string
        payment_state:
          type: string
        shipment_state:
          type: string
        payments_path:
          type: string
        shipments_path:
          type: string
        ship_path:
          type: string
        ready_to_ship:
          type: boolean
        created_at:
          type: string
        distributor_name:
          type: string
        special_instructions:
          type: string
        payment_capture_path:
          type: string
        distributor:
          type: object
          properties:
            id:
              type: integer
        order_cycle:
          type: object
          properties:
            id:
              type: integer

    Shipment:
      type: object
      properties:
        selected_shipping_rate_id:
          type: integer

    Enterprise:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        owner_id:
          type: integer

    EnterpriseShopfront:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        latitude:
          type: integer
        longitude:
          type: integer
        long_description:
          type: string
        website:
          type: string
        instagram:
          type: string
        linkedin:
          type: string
        twitter:
          type: string
        facebook:
          type: string
        is_primary_producer:
          type: boolean
        is_distributor:
          type: boolean
        phone:
          type: string
        visible:
          type: boolean
        email_address:
          type: string
        hash:
          type: string
        logo:
          type: string
        promo_image:
          type: string
        path:
          type: string
        category:
          type: string
        active:
          type: boolean
        producers:
          type: array
          items:
            $ref: '#/components/schemas/EnterpriseThin'
        orders_close_at:
          type: string
        hubs:
          type: array
          items:
            $ref: '#/components/schemas/EnterpriseThin'
        taxons:
          type: array
          items:
            type: string
        supplied_taxons:
          type: array
          items:
            type: string
        pickup:
          type: boolean
        delivery:
          type: boolean
        address:
          type: array
          items:
            $ref: '#/components/schemas/Address'

    EnterpriseThin:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        active:
          type: boolean
        path:
          type: string
        address:
          $ref: '#/components/schemas/Address'

    Address:
      type: object
      properties:
        id:
          type: integer
        zipcode:
          type: string
        city:
          type: string
        state_name:
          type: string
        state_id:
          type: integer
        phone:
          type: string
        firstname:
          type: string
        lastname:
          type: string
        address1:
          type: string
        address2:
          type: string
        country_id:
          type: integer

    Customer:
      type: object
      properties:
        id:
          type: integer
        enterprise_id:
          type: integer
        name:
          type: string
        code:
          type: string
        email:
          type: string
        allow_charges:
          type: boolean

    Taxon:
      type: object
      properties:
        name:
          type: string
        taxonomy_id:
          type: integer
        position:
          type: integer
        permalink:
          type: string
        taxons:
          type: array
          items:
            $ref: '#/components/schemas/Taxon'
        pretty_name:
          type: string
        id:
          type: integer
        parent_id:
          type: integer
        icon:
          type: string

    TaxonJstree:
      type: object
      properties:
        data:
          type: string
        state:
          type: string
        attr:
          type: object
          properties:
            id:
              type: integer
            name:
              type: string

    Cookies_Consent:
      type: object
      properties:
        cookies_consent:
          type: boolean
      example:
        cookies_consent: false