Canal Max Shipping Rates API

openapi: 3.2.0
info:
  title: Rokt Catalog Max Shipping Rates API
  version: 1.0.1
  description: Integrate with Rokt Catalog
servers:
- url: https://api.shopcanal.com/platform
  description: Rokt Catalog Storefront Public API
tags:
- name: max-shipping-rates
paths:
  /max-shipping-rates/:
    post:
      operationId: max_shipping_rates_create
      description: '**[Storefront Only]** Provide a rough, potentially overestimated shipping cost for a set of line items, useful for display *before* a customer provides their full address (e.g., showing ''Shipping from $X'' on a product page).


        **Request Body (`MaxShippingQuerySerializer`):**


        - `line_items` (list, required): A list of objects, each specifying:


        - `variant_id` (UUID, required): The Rokt Catalog ID of the *Storefront''s* variant record.


        - `quantity` (integer, required): The quantity of this variant.


        **Process:**


        1. **Default Address:** This endpoint **ignores** any address provided and instead uses a **hardcoded default address** (currently hardcoded to San Francisco, CA: 655 Montgomery St, 94111).


        2. **Query Suppliers:** It queries the relevant Suppliers for shipping rates to this *default* address using the provided `line_items`.


        3. **Find Maximum:** It identifies the **single highest shipping rate** returned across all involved Suppliers for the default address.


        **Response (`ShippingRateResponseSerializer`):**


        - `rates` (list): Typically contains **only one** rate object representing the maximum cost found for the default address. The object includes `title` and `price` (Money object).


        **Disclaimer:** This is an **estimate** based on a fixed location. The actual shipping cost calculated using the customer''s real address via the `/shipping_rates` endpoint during checkout may be significantly different (higher or lower).'
      tags:
      - max-shipping-rates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MaxShippingQuery'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MaxShippingQuery'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MaxShippingQuery'
        required: true
      security:
      - platformAppId: []
        platformAppToken: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingRateResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: ''
      summary: Max shipping rates create
      x-summary-source: derived
components:
  schemas:
    ShippingRate:
      type: object
      properties:
        code:
          type: string
        title:
          type: string
        price:
          type: number
          format: double
        currency:
          type: string
          default: USD
      required:
      - code
      - price
      - title
    Error:
      type: object
      properties:
        message:
          type: string
        detail: {}
    CreateOrderLineItem:
      type: object
      properties:
        variant_id:
          type: string
          format: uuid
        quantity:
          type: integer
        price:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,4})?$
      required:
      - quantity
      - variant_id
    MaxShippingQuery:
      type: object
      properties:
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/CreateOrderLineItem'
      required:
      - line_items
    ShippingRateResponse:
      type: object
      properties:
        shipping_rates:
          type: array
          items:
            $ref: '#/components/schemas/ShippingRate'
      required:
      - shipping_rates
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    platformAppId:
      type: apiKey
      in: header
      name: X-CANAL-APP-ID
    platformAppToken:
      type: apiKey
      in: header
      name: X-CANAL-APP-TOKEN