openapi: 3.0.3
info:
  title: Claims Resolution API
  termsOfService: https://useonward.com/terms-and-conditions
  contact:
    email: help@useonward.com
  version: 1.0.0
servers:
  - url: https://api.your-store.com/onward
tags:
  - name: Claims Resolution
    description: >-
      In order for Onward to resolve claims we need to be able issue refunds,
      reorders, and store credit in your system. This can be done by registering
      your Claims Resolution URL in our system and properly responding to the
      requests that will be sent.<br/>See our guide on [implementing our Claims
      Resolution API](../guides/resolving_claims.md).
paths:
  /orders/{shopOrderId}/refund:
    post:
      tags:
        - Claims Resolution
      summary: Refund an order
      description: >-
        Onward is requesting a claim to be resolved via refunding products for
        the specified Order in your platform.
      operationId: claimsRefund
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
        - name: shopOrderId
          in: path
          description: Your ID for the Order
          required: true
          example: '18282'
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                shop_order_id:
                  type: string
                  description: Your ID for the Order this refund relates to
                  example: '18282'
                onward_refundable:
                  type: object
                  description: Record that trigged this refund
                  properties:
                    id:
                      type: integer
                      format: int32
                      description: Our ID
                      example: '456001'
                    type:
                      type: string
                      description: Kind of record
                      example: Claim
                  required:
                    - id
                    - type
                line_items:
                  type: array
                  items:
                    type: object
                    properties:
                      to_issue_amount:
                        description: Amount to refund in the specified currency
                        type: object
                        properties:
                          currency:
                            type: string
                            example: USD
                          cents:
                            type: integer
                            format: int32
                            example: 1099
                      to_issue_amount_presentment:
                        description: Amount to refund in the currency the customer uses
                        type: object
                        properties:
                          currency:
                            type: string
                            example: CAD
                          cents:
                            type: integer
                            format: int32
                            example: 1525
                      shop_line_item_id:
                        type: string
                        description: Your ID for the line item being refunded
                        example: '91827'
                      quantity_to_issue:
                        type: integer
                        format: int32
                        description: Number of items to refund
                        example: 1
                    required:
                      - to_issue_amount
                      - to_issue_amount_presentment
                      - shop_line_item_id
                      - quantity_to_issue
              required:
                - shop_order_id
                - line_items
                - onward_refundable
      responses:
        '200':
          description: Order refunded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  shop_refund_id:
                    type: string
                    description: Your ID for the refund
                    example: '123456'
                required:
                  - shop_refund_id
        '404':
          description: Order not found
        '422':
          description: Validation exception
      security:
        - api_key: []
  /orders/{shopOrderId}/reorder:
    post:
      tags:
        - Claims Resolution
      summary: Reorder items
      description: >
        Onward is requesting a claim to be resolved via reordering products for
        the Order in your platform.

        In addition to replying with `shop_order_id` & `shop_order_number` you
        also need to send the order in the regular channel (`POST /orders`).
      operationId: claimsReorder
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/Accept'
        - name: shopOrderId
          in: path
          description: Your ID for the original Order
          required: true
          example: '190102'
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                onward_reorderable:
                  type: object
                  description: Record that trigged this reorder
                  properties:
                    id:
                      type: integer
                      format: int32
                      description: Our ID
                      example: '356001'
                    type:
                      type: string
                      description: Kind of record
                      example: Claim
                  required:
                    - id
                    - type
                line_items:
                  type: array
                  items:
                    type: object
                    properties:
                      shop_line_item_id:
                        type: string
                        description: The line item ID from the original order
                        example: LI-1989
                      quantity_to_issue:
                        type: integer
                        description: The quantity to reorder
                    required:
                      - shop_line_item_id
                      - quantity_to_issue
                customer:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    email:
                      type: string
                      format: email
                    phone_number:
                      type: string
                shipping_address:
                  $ref: '#/components/schemas/Address'
              required:
                - shipping_address
                - customer
                - line_items
                - onward_reorderable
      responses:
        '200':
          description: Order refunded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  shop_order_id:
                    type: string
                    description: Your ID for the new Order
                    example: '123456'
                  shop_order_number:
                    type: string
                    description: >-
                      The Order Number of this new Order as presented to the
                      customer
                    example: IN-94713
                required:
                  - shop_order_id
                  - shop_order_number
        '404':
          description: Order not found
        '422':
          description: Validation exception
      security:
        - api_key: []
  /orders/{shopOrderId}/store_credit:
    post:
      tags:
        - Claims Resolution
      summary: Issue store credit
      description: >-
        Onward is requesting a claim to be resolved via store credit for a
        specific Order in your platform.
      operationId: claimsStoreCredit
      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:
              type: object
              properties:
                customer:
                  type: object
                  properties:
                    first_name:
                      type: string
                    last_name:
                      type: string
                    email:
                      type: string
                      format: email
                    phone_number:
                      type: string
                to_issue_amount:
                  description: Amount to refund in the specified currency
                  type: object
                  properties:
                    currency:
                      type: string
                      example: USD
                    cents:
                      type: integer
                      format: int32
                      example: 1099
                  required:
                    - currency
                    - cents
              required:
                - customer
                - to_issue_amount
      responses:
        '200':
          description: Store credit issued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  shop_store_credit_id:
                    type: string
                    description: Your ID for the store credit
                    example: GC123456
                  initial_value:
                    type: object
                    description: Initial balance of this store credit
                    properties:
                      currency:
                        type: string
                        example: USD
                      cents:
                        type: integer
                        format: int32
                        example: 1099
                  balance:
                    type: object
                    description: Current balance of this store credit
                    properties:
                      currency:
                        type: string
                        example: USD
                      cents:
                        type: integer
                        format: int32
                        example: 1099
                  note:
                    type: string
                    description: Any note for this store credit
                required:
                  - shop_store_credit_id
                  - initial_value
                  - balance
        '404':
          description: Order not found
        '422':
          description: Validation exception
      security:
        - api_key: []
components:
  parameters:
    ContentType:
      name: Content-Type
      in: header
      required: true
      example: application/json
      description: Content-Type must be application/json
      schema:
        type: string
    Accept:
      name: Accept
      in: header
      required: true
      example: application/json
      description: Accept must be application/json
      schema:
        type: string
  schemas:
    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
        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
        - amount_insured
        - purchased_quote_token
        - created_at
        - financial_status
        - customer
        - shipping_address
        - line_items
    UpdateOrder:
      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 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
        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
    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
    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 shop's currency
          example:
            cents: 500
            currency: USD
        total_price:
          description: Line item total in shop's currency
          example:
            cents: 1000
            currency: USD
        total_price_presentment:
          description: Line item total in customer's currency
          example:
            cents: 1000
            currency: USD
        quantity:
          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:
          description: Weight of the item in grams
          example: 24
        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 shop'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
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-API-Key
