openapi: 3.2.0
info:
  title: Drop Shipment Cancellation API
  version: 1.0.0
  contact:
    name: Fulfillment
  description: '## Introduction

    The Drop Ship is used to communicate to the client once an order has been shipped or cancelled from OptiTurn, to close an order within the client''s OMS.

    ### Post Confirmation:

    The Drop Shipment Confirmation API is used to post a shipment confirmation for the orders shipped so that the client can close the order on their end. Optoro can POST a shipment confirmation to the client endpoint.

    ### Post Cancellation:

    The Drop Shipment Cancellation API is used to post a cancelled order to a client endpoint. An order could be rejected or cancelled in the warehouse, due to the inventory not being found or it being damaged.

    ### Post Partial Cancellation:

    The Drop Shipment Partial Cancellation API is used to post a partially cancelled order to a client endpoint. An order item could be cancelled in the warehouse, due to the inventory is not being found or damaged.

    ## Failure Handling

    <p>When Optoro receives a 401 HTTP status, Optoro will request a new Authentication Token from the client''s services and retry the request.</p> <p>When Optoro receives any other error (as described above and identified by a 4xx (not 401) or 5xx range http status code) Optoro will retry five times with the same message.  The retries will happen at an exponential backoff cadence in order not to overload machines.  If the failure persists, the message will be stored in a failure queue and Optoro will have a technical contact person reach out to client tech support to report a problem.  When the problem has been resolved, Optoro can manually retry failed requests.</p> <p>For Drop Shipment acknowledgement, all errors are handled the same since this is not in a user facing flow.  However, the differentiation of status codes will help Optoro when reporting an issue.</p>

    '
servers:
- url: https://developer.optoro.com
tags:
- name: Drop Shipment Cancellation
paths:
  /drop_shipment_cancellation:
    post:
      summary: POST a Drop Shipment Cancellation
      operationId: drop_shipment_cancellation
      description: 'Client endpoint to which Drop Shipment Cancellation data is posted to.

        <br>This endpoint along with any authentication mechanisms needed must be communicated to client''s account manager.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DropShipmentCancellation'
      responses:
        '200':
          description: Success. Optoro recommends client APIs respond with a JSON-structured object. This is used for debugging purposes only so this guidance is technically optional.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationFailure'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/ServerUnavailable'
      tags:
      - Drop Shipment Cancellation
components:
  responses:
    InternalServerError:
      description: Internal Server Error
    Unauthorized:
      description: Not Authorized. A new authentication token will be requested from the client's services and the request will be retried.
    ServerUnavailable:
      description: Client Server Unavailable
    BadRequest:
      description: Bad Request
  schemas:
    ValidationFailure:
      type: object
      required:
      - message
      - errors
      properties:
        message:
          type: string
          description: Summary of the error(s).
        errors:
          type: array
          description: Contains one or more error objects.
          items:
            type: object
            required:
            - field
            - code
            description: Describes a single validation failure.
            properties:
              field:
                type: string
                description: JSON path of the field that failed validation.
              code:
                type: string
                description: Categorization of validation failure. Defaults to 'invalid'.
                enum:
                - missing_field
                - invalid_type
                - invalid
    DropShipmentCancellation:
      type: object
      description: Drop Shipment Cancellation Data
      properties:
        order:
          type: object
          properties:
            id:
              type: integer
              description: An object's database primary key. Do not rely on this value!
              example: 1
            client_identifier:
              type: string
              description: client_identifier associated with the shipment which is also associated with the order
              example: 3fda4c37-6830-469f-b343-9d1a482a97fd
            billing_address:
              type: object
              properties:
                id:
                  type: integer
                  description: An object's database primary key. Do not rely on this value!
                  example: 1
                name:
                  type: string
                  description: Name for the address.
                  example: Lacy Macejkovic
                company:
                  type: string
                  description: Company name for the address.
                  example: Bayer-Abernathy
                telephone_number:
                  type: string
                  description: Telephone number linked to the address.
                  example: (914) 000-8971
                street:
                  type: string
                  description: Street line 1 of the address.
                  example: 315 5th Ave
                street2:
                  type: string
                  description: Street line 2 of the address.
                  example: Suite 2112
                city:
                  type: string
                  description: City of the address.
                  example: Scarsdale
                state:
                  type: string
                  description: State of the address.
                  example: NY
                zip_code:
                  type: string
                  description: Zip code of the address.
                  example: '10583'
                country:
                  type: string
                  description: Country of the address.
                  example: US
                created_at:
                  type: string
                  format: date-time
                  description: Creation timestamp iso8601 UTC
                updated_at:
                  type: string
                  format: date-time
                  description: Timestamp of most recent update iso8601 UTC
              additionalProperties: false
            shipping_address:
              type: object
              properties:
                id:
                  type: integer
                  description: An object's database primary key. Do not rely on this value!
                  example: 1
                name:
                  type: string
                  description: Name for the address.
                  example: James Carter
                company:
                  type: string
                  description: Company name for the address.
                  example: Carter Industries
                telephone_number:
                  type: string
                  description: Telephone number linked to the address.
                  example: (206) 555-1208
                street:
                  type: string
                  description: Street line 1 of the address.
                  example: 121 Vine Street
                street2:
                  type: string
                  description: Street line 2 of the address.
                  example: Suite 1200
                city:
                  type: string
                  description: City of the address.
                  example: Seattle
                state:
                  type: string
                  description: State of the address.
                  example: WA
                zip_code:
                  type: string
                  description: Zip code of the address.
                  example: '98121'
                country:
                  type: string
                  description: Country of the address.
                  example: US
                created_at:
                  type: string
                  format: date-time
                  description: Creation timestamp iso8601 UTC
                updated_at:
                  type: string
                  format: date-time
                  description: Timestamp of most recent update iso8601 UTC
              additionalProperties: false
            brand:
              type: string
              description: Brand name of client that received the order.
              example: acme
            shipping_method:
              type: string
              description: 'The shipping method to be used on the order.

                '
              enum:
              - STANDARD
              - EXPRESS
              - OVERNIGHT
              - FREIGHT
              - PICK-UP
            status:
              type: string
              description: Status of the order.
              example: cancelled
            price_cents:
              type: integer
              description: Price paid in cents for the order.
              example: 10000
            tax_cents:
              type: integer
              description: Tax paid in cents for the order.
              example: 1000
            processing_fee_cents:
              type: integer
              description: Processing fee paid in cents for the order.
              example: 0
            shipping_cost_cents:
              type: integer
              description: Shipping cost paid in cents for the order.
              example: 500
            shipping_tax_cents:
              type: integer
              description: Shipping tax paid in cents for the order.
              example: 0
            comments:
              type: string
              description: Comments regarding the order.
              example: Sample order instructions
            expected_delivery_date:
              type: string
              format: date
              description: Expected delivery date of the order.
            signature_required:
              type: boolean
              description: Specifies if a customer signature is required on delivery
            packing_slip_identifier:
              type: string
              description: Packing slip identifier for the order.
              example: '1497064'
            reject_reason:
              type: string
              description: Reason the order was rejected.
              example: ''
            order_items:
              type: array
              description: Order Item attributes
              items:
                type: object
                properties:
                  id:
                    type: integer
                    description: An object's database primary key. Do not rely on this value!
                    example: 1
                  client_identifier:
                    type: string
                    description: The order item identifier for the order item, typically coming from the customer's ecommerce platform or OMS
                    example: 296f0b98-7bc5-4750-8cb9-2e36db1ff766
                  sku:
                    type: string
                    description: Item SKU or listing identifier. This will always be listing.identifier
                    example: PTBQ121308
                  brand:
                    type: string
                    description: The brand name of the order item
                    example: test_brand
                  condition:
                    type: string
                    description: The condition code for the order item
                    example: N
                  quantity:
                    type: integer
                    description: The quantity of the order item
                    example: 1
                  price_cents:
                    type: integer
                    description: The price in cents for the total quantity of the order item
                    example: 10000
                  tax_cents:
                    type: integer
                    description: The tax in cents for the total quantity of the order item
                    example: 1000
                  shipping_cost_cents:
                    type: integer
                    description: The shipping cost paid in cents for the order item
                    example: 500
                  shipping_tax_cents:
                    type: integer
                    description: The shipping tax paid in cents for the order item
                    example: 0
                  status:
                    type: string
                    description: Status of the order item
                    example: cancelled
                  comments:
                    type: string
                    description: Comments associated with the order item
                    example: ''
                additionalProperties: false
                required:
                - client_identifier
                - sku
                - brand
                - condition
                - quantity
                - price_cents
                - tax_cents
                - shipping_cost_cents
                - shipping_tax_cents
                - status
            created_at:
              type: string
              format: date-time
              description: Date in ISO 8601 format in UTC
            updated_at:
              type: string
              format: date-time
              description: Date in ISO 8601 format in UTC
          additionalProperties: false
          required:
          - client_identifier
          - billing_address
          - shipping_address
          - brand
          - shipping_method
          - status
          - price_cents
          - tax_cents
          - shipping_cost_cents
          - shipping_tax_cents
          - order_items