openapi: 3.0.3
info:
  title: Onward API
  termsOfService: https://useonward.com/terms-and-conditions
  contact:
    email: help@useonward.com
  version: 1.0.0
servers:
  - url: https://app.useonward.com/api/v1
tags:
  - name: Orders
    description: >-
      Your customers orders, including the information necessary for Onward to
      insure and handle claims.
  - name: Shipments
    description: Physical shipments of items within an order and their tracking events.
  - name: Quotes
    description: Insurance quotes for customers during checkout.
paths:
  /orders:
    post:
      tags:
        - Orders
      summary: Create an order
      description: >-
        When a customer places an order in your e-comm platform, create that
        order with its details in Onward.
      operationId: createOrder
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderInput'
        required: true
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '409':
          description: Order already exists
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  /orders/{shopOrderId}:
    patch:
      tags:
        - Orders
      summary: Update an order
      description: >-
        When order details change in your e-comm platform, update the order in
        Onward.
      operationId: updateOrder
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
        - name: shopOrderId
          in: path
          description: Your ID for the Order
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderInput'
        required: true
      responses:
        '200':
          description: Order updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
            application/xml:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  /orders/{shopOrderId}/refund_insurance:
    patch:
      tags:
        - Orders
      summary: Mark an order's insurance as refunded
      description: >-
        When you refund the patient for the insurnace amount in your e-comm
        platform, update the order's insurance status in Onward.
      operationId: refundInsurance
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
        - name: shopOrderId
          in: path
          description: Your ID for the Order
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Insurance refunded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '404':
          description: Order not found
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  /orders/{shopOrderId}/add_insurance:
    patch:
      tags:
        - Orders
      summary: Add insurance to an existing order
      description: >-
        If the customer did not purchase insurance during checkout, you can
        merchant-insure an order after-the-fact with this endpoint. Note: it is
        very important that you verify the status code of this request as not
        every order is eligible for insurance.
      operationId: addInsurance
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
        - name: shopOrderId
          in: path
          description: Your ID for the Order
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Insurance added successfully
        '404':
          description: Order not found
        '422':
          description: Could not add insurance
      security:
        - api_key: []
  /shipments:
    post:
      tags:
        - Shipments
      summary: Create a shipment
      description: When a you ship items for an order, create that shipment in Onward.
      operationId: createShipment
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shipment'
        required: true
      responses:
        '201':
          description: Shipment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '409':
          description: Shipment already exists
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  /shipments/{shopShipmentId}:
    patch:
      tags:
        - Shipments
      summary: Update a shipment
      description: >-
        When shipment details change in your e-comm platform, update the
        shipment in Onward.
      operationId: updateShipment
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
        - name: shopShipmentId
          in: path
          description: Your ID for the Shipment
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shipment'
        required: true
      responses:
        '200':
          description: Shipment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipment'
        '404':
          description: Shipment not found
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  /shipments/{shopShipmentId}/events:
    post:
      tags:
        - Shipments
      summary: Create a shipment event
      description: >-
        When a shipment status changes (e.g. it is shipped or out for delivery),
        notify Onward of that event.
      operationId: createShipmentEvent
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
        - name: shopShipmentId
          in: path
          description: Your ID for the Shipment
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShipmentEvent'
        required: true
      responses:
        '201':
          description: Shipment event created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShipmentEvent'
        '404':
          description: Shipment not found
        '409':
          description: Shipment event already exists
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
  /quotes:
    post:
      tags:
        - Quotes
      summary: Get an insurance quote
      description: >-
        During check out, get the insurance quote amount for the cart and add
        that amount to the order.
      operationId: createQuote
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                cart:
                  $ref: '#/components/schemas/Cart'
              required:
                - cart
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '422':
          description: Validation exception
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - api_key: []
components:
  parameters:
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: Content-Type must be application/json
      example: application/json
      schema:
        type: string
    Accept:
      name: Accept
      in: header
      required: true
      description: Accept must be application/json
      example: application/json
      schema:
        type: string
  schemas:
    ValidationError:
      properties:
        error:
          type: array
          description: >-
            Array of errors. Each error contains the field in the beginning
            followed by the issue found.
          items:
            description: Error messages
            type: string
            example: Name is required
          minItems: 1
    Order:
      type: object
      properties:
        shop_order_id:
          type: string
          description: Your ID for the Order
          example: '18282'
        shop_order_number:
          type: string
          description: The Order Number as presented to the customer
          example: W-94713
        subtotal_price:
          description: Order subtotal in shop's currency
          example:
            cents: 1999
            currency: USD
        subtotal_price_presentment:
          description: Order subtotal in customer's currency
          example:
            cents: 1999
            currency: USD
        total_discounts_price:
          description: Sum of applied discounts in shop's currency
          example:
            cents: 599
            currency: USD
        total_discounts_price_presentment:
          description: Sum of applied discounts in customer's currency
          example:
            cents: 599
            currency: USD
        total_shipping_price:
          description: Shipping amount in shop's currency
          example:
            cents: 299
            currency: USD
        total_shipping_price_presentment:
          description: Shipping amount in customer's currency
          example:
            cents: 299
            currency: USD
        total_tax_price:
          description: Total tax in shop's currency
          example:
            cents: 143
            currency: USD
        total_tax_price_presentment:
          description: Total tax in customer's currency
          example:
            cents: 143
            currency: USD
        total_price:
          description: Order total in shop's currency
          example:
            cents: 2499
            currency: USD
        total_price_presentment:
          description: Order total in customer's currency
          example:
            cents: 2499
            currency: USD
        insurance_paid:
          description: Insurance paid for this order by the customer
          example:
            cents: 2499
            currency: USD
        amount_insured:
          description: >-
            Sum of shippable line items that are being insured in shop's
            currency
          example:
            cents: 1200
            currency: USD
        amount_insured_presentment:
          description: >-
            Sum of shippable line items that are being insured in customer's
            currency
          example:
            cents: 1200
            currency: USD
        created_at:
          type: string
          format: date-time
          description: When the order was placed in your e-comm platform
          example: '2024-11-26T17:32:28Z'
        financial_status:
          type: string
          example: paid
          enum:
            - pending
            - paid
            - refunded
            - voided
        customer:
          $ref: '#/components/schemas/Customer'
        shipping_address:
          $ref: '#/components/schemas/Address'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
      required:
        - shop_order_id
        - shop_order_number
        - subtotal_price
        - total_discounts_price
        - total_shipping_price
        - total_tax_price
        - total_price
        - created_at
        - financial_status
        - customer
        - shipping_address
        - line_items
    CreateOrderInput:
      type: object
      properties:
        shop_order_id:
          type: string
          description: Your ID for the Order
          example: '18282'
        shop_order_number:
          type: string
          description: The Order Number as presented to the customer
          example: W-94713
        subtotal_price:
          description: Order subtotal in shop's currency
          example:
            cents: 1999
            currency: USD
        subtotal_price_presentment:
          description: Order subtotal in customer's currency
          example:
            cents: 1999
            currency: USD
        total_discounts_price:
          description: Sum of applied discounts in shop's currency
          example:
            cents: 599
            currency: USD
        total_discounts_price_presentment:
          description: Sum of applied discounts in customer's currency
          example:
            cents: 599
            currency: USD
        total_shipping_price:
          description: Shipping amount in shop's currency
          example:
            cents: 299
            currency: USD
        total_shipping_price_presentment:
          description: Shipping amount in customer's currency
          example:
            cents: 299
            currency: USD
        total_tax_price:
          description: Total tax in shop's currency
          example:
            cents: 143
            currency: USD
        total_tax_price_presentment:
          description: Total tax in customer's currency
          example:
            cents: 143
            currency: USD
        total_price:
          description: Order total in shop's currency
          example:
            cents: 2499
            currency: USD
        total_price_presentment:
          description: Order total in customer's currency
          example:
            cents: 2499
            currency: USD
        amount_insured:
          description: >-
            Sum of shippable line items that are being insured in shop's
            currency
          example:
            cents: 1200
            currency: USD
        amount_insured_presentment:
          description: >-
            Sum of shippable line items that are being insured in customer's
            currency
          example:
            cents: 1200
            currency: USD
        purchased_quote_token:
          type: string
          description: The quote being purchased, as received from Onward's Quote API
          example: >-
            c0740f7e3d4718a64fd9ce18101961d210d1c61c8c8afd62f95d62d8c433347b$$qkJClv/+sWfpOfPqp4sI46PxzBuBCW4eEDKsL4q87aFhRT9mdCpIuEWwuRuvbkX4BS8=--AUnUz8WgunyUiZ4o--nnYz0Lj5WsxSqsUxtBpIIQ==
        created_at:
          type: string
          format: date-time
          description: When the order was placed in your e-comm platform
          example: '2024-11-26T17:32:28Z'
        financial_status:
          type: string
          example: paid
          enum:
            - pending
            - paid
            - refunded
            - voided
        customer:
          $ref: '#/components/schemas/Customer'
        shipping_address:
          $ref: '#/components/schemas/Address'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
      required:
        - shop_order_id
        - shop_order_number
        - subtotal_price
        - total_discounts_price
        - total_shipping_price
        - total_tax_price
        - total_price
        - currency
        - created_at
        - financial_status
        - customer
        - shipping_address
        - line_items
    UpdateOrderInput:
      type: object
      properties:
        shop_order_number:
          type: string
          description: The Order Number as presented to the customer
          example: W-94713
        subtotal_price:
          description: Order subtotal in customer's currency
          example:
            cents: 1999
            currency: USD
        total_discounts_price:
          description: Sum of applied discounts in customer's currency
          example:
            cents: 599
            currency: USD
        total_shipping_price:
          description: Shipping amount in customer's currency
          example:
            cents: 299
            currency: USD
        total_tax_price:
          description: Total tax in customer's currency
          example:
            cents: 143
            currency: USD
        total_price:
          description: Order total in customer's currency
          example:
            cents: 2499
            currency: USD
        financial_status:
          type: string
          example: paid
          enum:
            - pending
            - paid
            - refunded
            - voided
        customer:
          $ref: '#/components/schemas/Customer'
        shipping_address:
          $ref: '#/components/schemas/Address'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
      required:
        - shop_order_number
        - subtotal_price
        - total_discounts_price
        - total_shipping_price
        - total_tax_price
        - total_price
        - currency
        - financial_status
        - customer
        - shipping_address
        - line_items
    Customer:
      type: object
      properties:
        shop_customer_id:
          type: string
          description: Your ID for the Customer
          example: '7461'
        first_name:
          type: string
          example: Sally
        last_name:
          type: string
          example: Loo
        email:
          type: string
          format: email
          example: sally@example.com
        phone_number:
          type: string
          format: phone
          example: '+13105551234'
      required:
        - shop_customer_id
        - first_name
        - last_name
    Address:
      type: object
      properties:
        address1:
          type: string
          example: 123 Main St
        address2:
          type: string
          example: Unit 50
        province_code:
          type: string
          example: CA
          description: Subdivision code (ISO-3166)
        city:
          type: string
          example: Los Angeles
        postal_code:
          type: string
          example: '90210'
        country_code:
          type: string
          example: US
          description: Alpha-2 country code (ISO-3166)
        phone_number:
          type: string
          format: phone
          example: '+13105551234'
      required:
        - address1
        - province_code
        - city
        - postal_code
        - country_code
        - phone_number
    LineItem:
      type: object
      properties:
        shop_line_item_id:
          type: string
          description: Your ID for the Line Item
          example: '816721'
        shop_product_id:
          type: string
          description: Your ID for the product
          example: '142'
        shop_variant_id:
          type: string
          description: Your ID or SKU for the variant
          example: '7261'
        name:
          type: string
          description: Name for the product and variant purchased
          example: Cool T-shirt - Red
        unit_price:
          description: Item price in order's currency
          example:
            cents: 500
            currency: USD
        total_price:
          description: Line item total in order's currency
          example:
            cents: 1000
            currency: USD
        total_price_presentment:
          description: Line item total in customer's currency
          example:
            cents: 1000
            currency: USD
        quantity:
          type: integer
          format: int32
          example: 2
        image_url:
          type: string
          format: url
          description: URL to an image of the item
          example: https://placecats.com/neo/300/200.png
        grams:
          type: integer
          format: int32
          description: Weight of the item in grams
          example: 24
        is_insured:
          type: boolean
          description: >-
            Whether the item should be insured by Onward (generally you should
            set this to true for shippable items and false for digital items).
            Requires purchase token and amount insured in the Order.
          example: true
        refunded_quantity:
          type: integer
          format: int32
          description: Number of items refunded (for full or partial refunds)
          example: 1
        refunded_price:
          description: Total refunded amount in order's currency
          example:
            cents: 500
            currency: USD
        refunded_price_presentment:
          description: Total refunded amount in customer's currency
          example:
            cents: 500
            currency: USD
      required:
        - shop_line_item_id
        - shop_product_id
        - shop_variant_id
        - name
        - unit_price
        - total_price
        - quantity
        - is_insured
        - image_url
        - grams
    Shipment:
      type: object
      properties:
        shop_shipment_id:
          type: string
          description: Your ID for the Shipment
          example: '3712'
        shop_order_id:
          type: string
          description: Your ID for the Order this Shipment relates to
          example: '18282'
        tracking_number:
          type: string
          description: Courier tracking number
          example: '780371515850'
        tracking_url:
          type: string
          description: URL to courier tracking page
          example: https://www.fedex.com/wtrk/track/?trknbr=780371515850
        tracking_company:
          type: string
          description: Courier name
          example: DHL Express
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
          description: The order line items included in this shipment
        created_at:
          type: string
          format: date-time
          description: When the shipment was created in your e-comm platform
          example: '2024-11-26T17:32:28Z'
      required:
        - shop_shipment_id
        - tracking_number
        - shop_order_id
        - tracking_company
        - line_items
        - created_at
    ShipmentEvent:
      type: object
      properties:
        shop_shipment_event_id:
          type: string
          description: Your ID for the Shipment
          example: '817391'
        status:
          type: string
          example: in_transit
          enum:
            - label_printed
            - label_purchased
            - attempted_delivery
            - ready_for_pickup
            - carrier_picked_up
            - confirmed
            - in_transit
            - out_for_delivery
            - delivered
            - delayed
            - failure
            - picked_up
        message:
          type: string
        estimated_delivery_at:
          type: string
          format: date-time
          example: '2024-11-26T17:32:28Z'
        created_at:
          type: string
          format: date-time
          description: When the event occurred in your e-comm platform
          example: '2024-11-26T17:32:28Z'
      required:
        - shop_shipment_event_id
        - status
        - created_at
    Cart:
      type: object
      properties:
        amount_insured:
          description: Sum of shippable line items that are being insured
          example:
            cents: 1999
            currency: USD
      required:
        - amount_insured
    Money:
      type: object
      properties:
        cents:
          type: integer
          format: int32
          example: 1299
        currency:
          type: string
          format: currency
          description: Currency code (ISO 4217)
          example: USD
      required:
        - cents
        - currency
    Quote:
      type: object
      properties:
        id:
          type: string
          description: Onward's ID for this Quote
          example: 8c0d0946dc595ecfe090ef85
        token:
          type: string
          description: >-
            Tokenized reference to this Quote that you will use when creating
            the insured Order after checkout
          example: >-
            c0740f7e3d4718a64fd9ce18101961d210d1c61c8c8afd62f95d62d8c433347b$$qkJClv/+sWfpOfPqp4sI46PxzBuBCW4eEDKsL4q87aFhRT9mdCpIuEWwuRuvbkX4BS8=--AUnUz8WgunyUiZ4o--nnYz0Lj5WsxSqsUxtBpIIQ==
        price:
          description: Price of insurance to be charged to the customer
          example:
            cents: 500
            currency: USD
        variant:
          type: object
          description: >-
            (Only included for Shopify shops) The Shopify Variant to add to cart
            in order to purchase this Quote
          properties:
            id:
              type: integer
              format: int32
              description: Shopify ID for the Variant
            sku:
              type: string
              description: Shopify SKU for the Variant
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-API-Key
