openapi: 3.0.0
info:
  version: 0.9.0
  title: Corso Commerce API
  description: >-

    The Corso Commerce API is designed to be accessed by e-commerce systems that
    need to send orders to Corso for potential coverage under Green Shipping
    Protection. It is intended to be used in conjunction with the Corso Shop
    API, sending orders to Corso that have been quoted for Green Shipping
    Protection and where the customer has elected to purchase it.


    ## Prerequisites


    Because this API is authenticated, it requires a Client ID and Client
    Secret. Please contact us in order to generate this auth pair if needed.


    Your fulfillment locations (warehouses where items are shipped to the
    customer from) must also be set up with Corso. This information is used to
    calculate carbon emissions, to complete the "Green" part of Green Shipping
    Protection.


    Various other pre-requisites will likely have already been completed for use
    of the Shop API, including the configuration of the Corso Green Shipping
    Protection products and variants.


    Note that all times are 'date-time' formatted strings, as one of the
    built-in formats officially defined by the Open API Specification:
    https://swagger.io/docs/specification/data-models/data-types/#string. Any
    date-time strings received without an offset will cause the request to fail.
            
  contact:
    email: support@corso.com
servers:
  - url: https://api.corso.com/v1
  - url: https://stg.api.corso.com/v1
tags:
  - name: Orders
    description: Data and operations to manage orders.
  - name: Store
    description: Data and operations needed to manage a store.
components:
  schemas:
    Orders:
      type: object
      properties:
        orderId:
          type: number
          example: 18372912
          description: >-
            The ID of the order in the Corso, used to interact with Corso
            systems.
        currencyConversionRate:
          type: number
          description: The conversion rate between store and customer
        storeId:
          type: number
          example: 9359
          description: >-
            The ID of the store in Corso systems. Some merchants may have
            multiple stores under a single API client_id, so this value should
            always be specified. Please contact Corso if you do not have this
            value for your integration.
        isShippingProtected:
          type: boolean
          example: true
          description: >-
            Whether or not the order is protected with Corso Green Shipping
            Protection.
        sourceOrderId:
          type: string
          example: '842810'
          description: >-
            The order identifier from the source platform. Is unique across the
            store, and typically across the entire platform used by the
            merchant.
        orderNumber:
          type: string
          description: >-
            The order number from the source platform, if none is provided.
            sourceOrderId will be used
        orderName:
          type: string
          description: >-
            Customer-facing identifier for the order the source platform. Often
            composed of the store-unique order number plus some modifying
            prefixes and suffixes.
          example: RDR-12345
        customer:
          allOf:
            - type: object
              properties:
                sourceCustomerId:
                  type: string
                  description: The customer ID (the source system).
                  example: '990986'
                firstName:
                  type: string
                  description: First name.
                  example: George
                lastName:
                  type: string
                  description: Last name.
                  example: Washington
              required:
                - sourceCustomerId
                - firstName
                - lastName
            - anyOf:
                - type: object
                  properties:
                    email:
                      type: string
                      description: Customer email address.
                      example: gwashington@mtvernon.org
                    phone:
                      type: string
                      description: Customer phone number is E-164 format.
                      example: '+16643443554'
                  required:
                    - email
                - type: object
                  properties:
                    email:
                      type: string
                      description: Customer email address.
                      example: gwashington@mtvernon.org
                    phone:
                      type: string
                      description: Customer phone number is E-164 format.
                      example: '+16643443554'
                  required:
                    - phone
          description: Object representing the customer who placed the order.
        lineItems:
          type: array
          items:
            type: object
            properties:
              sourceLineItemId:
                type: string
                description: The line item ID (from the source system).
                example: '990986'
              productId:
                type: string
                description: The product ID for the line item (from the source system).
                example: pro-33320
              variantId:
                type: string
                description: >-
                  The variant ID for the line item (from the source system). For
                  the line item that represents the Corso Green Shipping Product
                  (if purchased on the order), this should match the
                  corresponding variant ID stored by Corso in our system, so
                  that we can identify the order as protected.
                example: var-4569876332
              name:
                type: string
                description: >-
                  The line item name, typically the value shown to the customer
                  representing the product/variant combination purchased.
                example: 'Shorts - color: blue, size: small'
              quantity:
                type: number
                description: The quantity purchased for the line item.
                example: 1
              sku:
                type: string
                description: The SKU of product/variant of the line item.
                example: ITEM-12345
              tax:
                type: number
                description: Any tax applied to the line item.
                example: 1.23
                format: currency
              vendor:
                type: string
                description: The vendor of the line item
                example: Nike
              price:
                type: number
                description: The price of the line item
                example: 129.53
                format: currency
            required:
              - sourceLineItemId
              - productId
              - variantId
              - name
              - quantity
              - sku
              - tax
              - price
          minItems: 1
          description: Array of objects representing the line items on the order.
        createdOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the order was created in Corso systems.
        updatedOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the order was most recently updated in Corso systems.
        sourceCanceledOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the order was canceled in the source system.
        sourceCreatedOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the order was created in the source system.
        sourceUpdatedOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: >-
            Date/time when the order was most recently updated in the source
            system
        shippingMoney:
          type: number
          format: currency
          example: 1
          description: The cost of shipping the order as charged to the customer.
        subtotalMoney:
          type: number
          format: currency
          example: 10
          description: >-
            The subtotal of the order in the merchant's currency; typically
            equal to the cost of all product line items in the order totalled
            together.
        taxMoney:
          type: number
          format: currency
          example: 1
          description: >-
            The amount of all tax applied to the order as included in the order
            total.
        totalMoney:
          type: number
          format: currency
          example: 12
          description: >-
            The total amount charged to the customer. Must be equal to the sum
            of shippingMoney, subtotalMoney, and taxMoney, or the request will
            fail.
        billingAddress:
          type: object
          properties:
            name:
              type: string
              description: >-
                The name line on an address. Often the name of the customer, or
                the business name something is shipped to.
              example: Michael Jordan, c/o Chicago Bulls
            line1:
              type: string
              description: Address line 1, generally the street number and name.
              example: 1901 W Madison St
            line2:
              type: string
              description: >-
                Address line 2. Not mandatory, but often used for an apartment
                or suite number.
              example: Ste 101
            city:
              type: string
              description: City of the Address
              example: Chicago
            stateOrProvinceCode:
              type: string
              description: State or province code, typically 2 characters.
              example: IL
            postalCode:
              type: string
              description: Postal Code
              example: 60612-2459
            countryCode:
              type: string
              description: ISO 3166 country code
              example: USA
            latitude:
              type: number
            longitude:
              type: number
          required:
            - line1
            - city
            - stateOrProvinceCode
            - postalCode
            - countryCode
        shippingAddress:
          type: object
          properties:
            name:
              type: string
              description: >-
                The name line on an address. Often the name of the customer, or
                the business name something is shipped to.
              example: Michael Jordan, c/o Chicago Bulls
            line1:
              type: string
              description: Address line 1, generally the street number and name.
              example: 1901 W Madison St
            line2:
              type: string
              description: >-
                Address line 2. Not mandatory, but often used for an apartment
                or suite number.
              example: Ste 101
            city:
              type: string
              description: City of the Address
              example: Chicago
            stateOrProvinceCode:
              type: string
              description: State or province code, typically 2 characters.
              example: IL
            postalCode:
              type: string
              description: Postal Code
              example: 60612-2459
            countryCode:
              type: string
              description: ISO 3166 country code
              example: USA
            latitude:
              type: number
            longitude:
              type: number
          required:
            - line1
            - city
            - stateOrProvinceCode
            - postalCode
            - countryCode
        grams:
          type: number
          description: The weight of the order, in grams.
          example: 8783
        carbonGrams:
          type: number
          description: >-
            The amount of carbon offset for the order, in grams. Only available
            after fulfillment (when the shipping origin can be determined).
          example: 1338
        carbonCalculationMethod:
          type: string
          description: >-
            How the carbon was calculated, depending on the accuracy of the
            input data such as weight and distance.
          example: Calculated
        shippingTitle:
          type: string
          description: The name of the shipping plan used.
          example: FedEx 2nd Day Air
        canceledReason:
          type: string
          description: The reason the order was canceled.
          example: Order was created by mistake
        notes:
          type: string
          description: Any notes on the order
          example: Please use your red gift wrap, thank you!
        channel:
          type: string
          description: The name of the channel the order was created on.
          example: web
        channelId:
          type: string
          description: The ID of the sales channel the order was created from.
          example: d2d3d4d5
        customerCurrencyCode:
          type: string
          description: The 3 letter currency code used by the customer in ISO 4217 format
          example: USD
      required:
        - storeId
        - sourceOrderId
        - customer
        - lineItems
        - shippingMoney
        - subtotalMoney
        - taxMoney
        - totalMoney
        - billingAddress
        - shippingAddress
      additionalProperties: false
    Fulfillments:
      type: object
      properties:
        sourceFulfillmentId:
          type: string
          example: ACME-FULFILL-439823
          description: The ID of the fulfillment, as recorded in merchant systems.
        shippingWeightGrams:
          type: number
          description: The weight of the fulfillment in grams
        fulfillmentId:
          type: number
          description: The Corso ID of the fulfillment record
        fulfillmentLocationId:
          type: number
          description: The Corso ID of the location the order is fulfilled from.
        deliveredOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: ' Date/time when the fulfillment was delivered.'
        trackingInfoCompany:
          type: string
          description: The courier used to ship the fulfillment.
          example: USPS
        trackingInfoNumber:
          type: string
          description: The tracking number for the fulfillment.
          example: UPS-12345
        trackingInfoUrl:
          type: string
          format: url
          description: The URL to track the fulfillment.
          example: https://www.ups.com/track?loc=en_US&tracknum=1Z12345E0291980793
        estimatedDeliveryOn:
          type: string
          format: date-time
          description: Date/time when the fulfillment is estimated to be delivered on.
        shipmentStatus:
          type: string
          description: The status of the shipment.
          example: in_transit
        inTransitOn:
          type: string
          format: date-time
          description: Date/time when the fulfillment was shipped.
        createdOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the fulfillment was created Corso systems.
        updatedOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the fulfillment was updated in Corso systems.
        sourceCreatedOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the fulfillment was created in the source system.
      required:
        - sourceFulfillmentId
        - fulfillmentId
        - fulfillmentLocationId
    Fulfillment List:
      type: object
      properties:
        fulfillments:
          type: array
          items:
            type: object
            properties:
              sourceFulfillmentId:
                type: string
                example: ACME-FULFILL-439823
                description: The ID of the fulfillment, as recorded in merchant systems.
              shippingWeightGrams:
                type: number
                description: The weight of the fulfillment in grams
              fulfillmentId:
                type: number
                description: The Corso ID of the fulfillment record
              fulfillmentLocationId:
                type: number
                description: The Corso ID of the location the order is fulfilled from.
              deliveredOn:
                type: string
                format: date-time
                example: '2022-01-01T17:32:28Z'
                description: ' Date/time when the fulfillment was delivered.'
              trackingInfoCompany:
                type: string
                description: The courier used to ship the fulfillment.
                example: USPS
              trackingInfoNumber:
                type: string
                description: The tracking number for the fulfillment.
                example: UPS-12345
              trackingInfoUrl:
                type: string
                format: url
                description: The URL to track the fulfillment.
                example: >-
                  https://www.ups.com/track?loc=en_US&tracknum=1Z12345E0291980793
              estimatedDeliveryOn:
                type: string
                format: date-time
                description: >-
                  Date/time when the fulfillment is estimated to be delivered
                  on.
              shipmentStatus:
                type: string
                description: The status of the shipment.
                example: in_transit
              inTransitOn:
                type: string
                format: date-time
                description: Date/time when the fulfillment was shipped.
              createdOn:
                type: string
                format: date-time
                example: '2022-01-01T17:32:28Z'
                description: Date/time when the fulfillment was created Corso systems.
              updatedOn:
                type: string
                format: date-time
                example: '2022-01-01T17:32:28Z'
                description: Date/time when the fulfillment was updated in Corso systems.
              sourceCreatedOn:
                type: string
                format: date-time
                example: '2022-01-01T17:32:28Z'
                description: >-
                  Date/time when the fulfillment was created in the source
                  system.
            required:
              - sourceFulfillmentId
              - fulfillmentId
              - fulfillmentLocationId
      required:
        - fulfillments
    Line Items:
      type: object
      properties:
        orderId:
          type: number
          description: The ID of the order the line item belongs to in Corso systems.
          example: 18372912
        lineItemId:
          type: number
          description: The ID of the line item in Corso systems.
          example: 18372912
        sourceCanceledOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: Date/time when the order was canceled in Corso systems.
        createdOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: ' Date/time when the order was created Corso systems.'
        updatedOn:
          type: string
          format: date-time
          example: '2022-01-01T17:32:28Z'
          description: ' Date/time when the order was created in Corso systems.'
        sourceLineItemId:
          type: string
          description: The line item ID (from the source system).
          example: '990986'
        productId:
          type: string
          description: The product ID for the line item (from the source system).
          example: pro-33320
        variantId:
          type: string
          description: >-
            The variant ID for the line item (from the source system). For the
            line item that represents the Corso Green Shipping Product (if
            purchased on the order), this should match the corresponding variant
            ID stored by Corso in our system, so that we can identify the order
            as protected.
          example: var-4569876332
        name:
          type: string
          description: >-
            The line item name, typically the value shown to the customer
            representing the product/variant combination purchased.
          example: 'Shorts - color: blue, size: small'
        quantity:
          type: number
          description: The quantity purchased for the line item.
          example: 1
        sku:
          type: string
          description: The SKU of product/variant of the line item.
          example: ITEM-12345
        tax:
          type: number
          description: Any tax applied to the line item.
          example: 1.23
          format: currency
        vendor:
          type: string
          description: The vendor of the line item
          example: Nike
        price:
          type: number
          description: The price of the line item
          example: 129.53
          format: currency
      required:
        - orderId
        - lineItemId
        - sourceLineItemId
        - productId
        - variantId
        - name
        - quantity
        - sku
        - tax
        - price
    Store:
      type: object
      properties:
        storeId:
          type: number
          description: >-
            The ID of the store in Corso systems. Most operations will require a
            store ID, since an authenticated API connection could potentially
            have permissions to manage resources for multiple stores.
          example: 6734
        currencyCode:
          type: string
          description: >-
            The 3 letter currency code used by the store (in ISO 4217 format).
            This currency code is used as the basis for all money values
            transmitted via the API including order totals, line item values,
            and similar.
          example: USD
        ianaTimezone:
          type: string
          description: >-
            The timezone for the store. Used as a factor when calculating
            invoice time periods, reorder windows, and similar time-based
            evaluations.
          example: America/Denver
      required:
        - storeId
        - currencyCode
        - ianaTimezone
  parameters: {}
paths:
  /stores/{storeId}:
    get:
      tags:
        - Store
      description: >-
        This endpoint allows an API to retrieve data about Corso's
        representation of the store. This can be useful for verifying store
        properties used elsewhere by the API.
      summary: Get a store
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso Id for the store
          name: storeId
          in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Store'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /orders:
    post:
      tags:
        - Orders
      description: >-
        Create a new order in Corso systems, to represent a purchase by a
        customer of the merchant. An order should be created regardless of
        whether or not it is protected by Green Shipping Protection, to allow
        Corso staff to assist customers in knowing whether their order is
        protected.
            
      summary: Create an order
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                currencyConversionRate:
                  type: number
                  description: The conversion rate between store and customer
                storeId:
                  type: number
                  example: 9359
                  description: >-
                    The ID of the store in Corso systems. Some merchants may
                    have multiple stores under a single API client_id, so this
                    value should always be specified. Please contact Corso if
                    you do not have this value for your integration.
                sourceOrderId:
                  type: string
                  example: '842810'
                  description: >-
                    The order identifier from the source platform. Is unique
                    across the store, and typically across the entire platform
                    used by the merchant.
                orderNumber:
                  type: string
                  description: >-
                    The order number from the source platform, if none is
                    provided. sourceOrderId will be used
                orderName:
                  type: string
                  description: >-
                    Customer-facing identifier for the order the source
                    platform. Often composed of the store-unique order number
                    plus some modifying prefixes and suffixes.
                  example: RDR-12345
                customer:
                  allOf:
                    - type: object
                      properties:
                        sourceCustomerId:
                          type: string
                          description: The customer ID (the source system).
                          example: '990986'
                        firstName:
                          type: string
                          description: First name.
                          example: George
                        lastName:
                          type: string
                          description: Last name.
                          example: Washington
                      required:
                        - sourceCustomerId
                        - firstName
                        - lastName
                    - anyOf:
                        - type: object
                          properties:
                            email:
                              type: string
                              description: Customer email address.
                              example: gwashington@mtvernon.org
                            phone:
                              type: string
                              description: Customer phone number is E-164 format.
                              example: '+16643443554'
                          required:
                            - email
                        - type: object
                          properties:
                            email:
                              type: string
                              description: Customer email address.
                              example: gwashington@mtvernon.org
                            phone:
                              type: string
                              description: Customer phone number is E-164 format.
                              example: '+16643443554'
                          required:
                            - phone
                  description: Object representing the customer who placed the order.
                lineItems:
                  type: array
                  items:
                    type: object
                    properties:
                      sourceLineItemId:
                        type: string
                        description: The line item ID (from the source system).
                        example: '990986'
                      productId:
                        type: string
                        description: >-
                          The product ID for the line item (from the source
                          system).
                        example: pro-33320
                      variantId:
                        type: string
                        description: >-
                          The variant ID for the line item (from the source
                          system). For the line item that represents the Corso
                          Green Shipping Product (if purchased on the order),
                          this should match the corresponding variant ID stored
                          by Corso in our system, so that we can identify the
                          order as protected.
                        example: var-4569876332
                      name:
                        type: string
                        description: >-
                          The line item name, typically the value shown to the
                          customer representing the product/variant combination
                          purchased.
                        example: 'Shorts - color: blue, size: small'
                      quantity:
                        type: number
                        description: The quantity purchased for the line item.
                        example: 1
                      sku:
                        type: string
                        description: The SKU of product/variant of the line item.
                        example: ITEM-12345
                      tax:
                        type: number
                        description: Any tax applied to the line item.
                        example: 1.23
                        format: currency
                      vendor:
                        type: string
                        description: The vendor of the line item
                        example: Nike
                      price:
                        type: number
                        description: The price of the line item
                        example: 129.53
                        format: currency
                    required:
                      - sourceLineItemId
                      - productId
                      - variantId
                      - name
                      - quantity
                      - sku
                      - tax
                      - price
                  minItems: 1
                  description: Array of objects representing the line items on the order.
                sourceCreatedOn:
                  type: string
                  format: date-time
                  example: '2022-01-01T17:32:28Z'
                  description: Date/time when the order was created in the source system.
                sourceUpdatedOn:
                  type: string
                  format: date-time
                  example: '2022-01-01T17:32:28Z'
                  description: >-
                    Date/time when the order was most recently updated in the
                    source system
                shippingMoney:
                  type: number
                  format: currency
                  example: 1
                  description: The cost of shipping the order as charged to the customer.
                subtotalMoney:
                  type: number
                  format: currency
                  example: 10
                  description: >-
                    The subtotal of the order in the merchant's currency;
                    typically equal to the cost of all product line items in the
                    order totalled together.
                taxMoney:
                  type: number
                  format: currency
                  example: 1
                  description: >-
                    The amount of all tax applied to the order as included in
                    the order total.
                totalMoney:
                  type: number
                  format: currency
                  example: 12
                  description: >-
                    The total amount charged to the customer. Must be equal to
                    the sum of shippingMoney, subtotalMoney, and taxMoney, or
                    the request will fail.
                billingAddress:
                  type: object
                  properties:
                    name:
                      type: string
                      description: >-
                        The name line on an address. Often the name of the
                        customer, or the business name something is shipped to.
                      example: Michael Jordan, c/o Chicago Bulls
                    line1:
                      type: string
                      description: Address line 1, generally the street number and name.
                      example: 1901 W Madison St
                    line2:
                      type: string
                      description: >-
                        Address line 2. Not mandatory, but often used for an
                        apartment or suite number.
                      example: Ste 101
                    city:
                      type: string
                      description: City of the Address
                      example: Chicago
                    stateOrProvinceCode:
                      type: string
                      description: State or province code, typically 2 characters.
                      example: IL
                    postalCode:
                      type: string
                      description: Postal Code
                      example: 60612-2459
                    countryCode:
                      type: string
                      description: ISO 3166 country code
                      example: USA
                    latitude:
                      type: number
                    longitude:
                      type: number
                  required:
                    - line1
                    - city
                    - stateOrProvinceCode
                    - postalCode
                    - countryCode
                shippingAddress:
                  type: object
                  properties:
                    name:
                      type: string
                      description: >-
                        The name line on an address. Often the name of the
                        customer, or the business name something is shipped to.
                      example: Michael Jordan, c/o Chicago Bulls
                    line1:
                      type: string
                      description: Address line 1, generally the street number and name.
                      example: 1901 W Madison St
                    line2:
                      type: string
                      description: >-
                        Address line 2. Not mandatory, but often used for an
                        apartment or suite number.
                      example: Ste 101
                    city:
                      type: string
                      description: City of the Address
                      example: Chicago
                    stateOrProvinceCode:
                      type: string
                      description: State or province code, typically 2 characters.
                      example: IL
                    postalCode:
                      type: string
                      description: Postal Code
                      example: 60612-2459
                    countryCode:
                      type: string
                      description: ISO 3166 country code
                      example: USA
                    latitude:
                      type: number
                    longitude:
                      type: number
                  required:
                    - line1
                    - city
                    - stateOrProvinceCode
                    - postalCode
                    - countryCode
                grams:
                  type: number
                  description: The weight of the order, in grams.
                  example: 8783
                carbonGrams:
                  type: number
                  description: >-
                    The amount of carbon offset for the order, in grams. Only
                    available after fulfillment (when the shipping origin can be
                    determined).
                  example: 1338
                carbonCalculationMethod:
                  type: string
                  description: >-
                    How the carbon was calculated, depending on the accuracy of
                    the input data such as weight and distance.
                  example: Calculated
                shippingTitle:
                  type: string
                  description: The name of the shipping plan used.
                  example: FedEx 2nd Day Air
                notes:
                  type: string
                  description: Any notes on the order
                  example: Please use your red gift wrap, thank you!
                channel:
                  type: string
                  description: The name of the channel the order was created on.
                  example: web
                channelId:
                  type: string
                  description: The ID of the sales channel the order was created from.
                  example: d2d3d4d5
                customerCurrencyCode:
                  type: string
                  description: >-
                    The 3 letter currency code used by the customer in ISO 4217
                    format
                  example: USD
              required:
                - storeId
                - sourceOrderId
                - customer
                - lineItems
                - shippingMoney
                - subtotalMoney
                - taxMoney
                - totalMoney
                - billingAddress
                - shippingAddress
              additionalProperties: false
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '409':
          description: Conflict
  /orders/{orderId}:
    get:
      tags:
        - Orders
      description: Retrieve the current representation of an order from Corso systems
      summary: Get an order
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    post:
      tags:
        - Orders
      description: >-
        Update an order. This endpoint accepts a body that contains ANY
        combination of the following fields. The Corso Commerce API does not
        accept PUT nor PATCH requests. If you wish to add or remove a line item,
        this must be performed with the line item endpoints.
      summary: Update an order
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                currencyConversionRate:
                  type: number
                  description: The conversion rate between store and customer
                orderName:
                  type: string
                  description: >-
                    Customer-facing identifier for the order the source
                    platform. Often composed of the store-unique order number
                    plus some modifying prefixes and suffixes.
                  example: RDR-12345
                sourceUpdatedOn:
                  type: string
                  format: date-time
                  example: '2022-01-01T17:32:28Z'
                  description: >-
                    Date/time when the order was most recently updated in the
                    source system
                shippingMoney:
                  type: number
                  format: currency
                  example: 1
                  description: The cost of shipping the order as charged to the customer.
                subtotalMoney:
                  type: number
                  format: currency
                  example: 10
                  description: >-
                    The subtotal of the order in the merchant's currency;
                    typically equal to the cost of all product line items in the
                    order totalled together.
                taxMoney:
                  type: number
                  format: currency
                  example: 1
                  description: >-
                    The amount of all tax applied to the order as included in
                    the order total.
                totalMoney:
                  type: number
                  format: currency
                  example: 12
                  description: >-
                    The total amount charged to the customer. Must be equal to
                    the sum of shippingMoney, subtotalMoney, and taxMoney, or
                    the request will fail.
                grams:
                  type: number
                  description: The weight of the order, in grams.
                  example: 8783
                shippingTitle:
                  type: string
                  description: The name of the shipping plan used.
                  example: FedEx 2nd Day Air
                notes:
                  type: string
                  description: Any notes on the order
                  example: Please use your red gift wrap, thank you!
                customer:
                  type: object
                  properties:
                    firstName:
                      type: string
                      description: First name.
                      example: George
                    lastName:
                      type: string
                      description: Last name.
                      example: Washington
                    email:
                      type: string
                      description: Customer phone number in E-164 format.
                      example: gwashington@mtvernon.org
                    phone:
                      type: string
                      description: Customer email address.
                      example: '+16643443554'
                billingAddress:
                  type: object
                  properties:
                    name:
                      type: string
                      description: >-
                        The name line on an address. Often the name of the
                        customer, or the business name something is shipped to.
                      example: Michael Jordan, c/o Chicago Bulls
                    line1:
                      type: string
                      description: Address line 1, generally the street number and name.
                      example: 1901 W Madison St
                    line2:
                      type: string
                      description: >-
                        Address line 2. Not mandatory, but often used for an
                        apartment or suite number.
                      example: Ste 101
                    city:
                      type: string
                      description: City of the Address
                      example: Chicago
                    stateOrProvinceCode:
                      type: string
                      description: State or province code, typically 2 characters.
                      example: IL
                    postalCode:
                      type: string
                      description: Postal Code
                      example: 60612-2459
                    countryCode:
                      type: string
                      description: ISO 3166 country code
                      example: USA
                    latitude:
                      type: number
                    longitude:
                      type: number
                shippingAddress:
                  type: object
                  properties:
                    name:
                      type: string
                      description: >-
                        The name line on an address. Often the name of the
                        customer, or the business name something is shipped to.
                      example: Michael Jordan, c/o Chicago Bulls
                    line1:
                      type: string
                      description: Address line 1, generally the street number and name.
                      example: 1901 W Madison St
                    line2:
                      type: string
                      description: >-
                        Address line 2. Not mandatory, but often used for an
                        apartment or suite number.
                      example: Ste 101
                    city:
                      type: string
                      description: City of the Address
                      example: Chicago
                    stateOrProvinceCode:
                      type: string
                      description: State or province code, typically 2 characters.
                      example: IL
                    postalCode:
                      type: string
                      description: Postal Code
                      example: 60612-2459
                    countryCode:
                      type: string
                      description: ISO 3166 country code
                      example: USA
                    latitude:
                      type: number
                    longitude:
                      type: number
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    delete:
      tags:
        - Orders
      description: >-
        Cancel an order in Corso systems. The order can still be retrieved, but
        not updated or otherwise modified after cancelation.
      summary: Cancel an order
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                canceledReason:
                  type: string
                  description: The reason the order was canceled.
                  example: Order was created by mistake
                sourceCanceledOn:
                  type: string
                  format: date-time
                  example: '2022-01-01T17:32:28Z'
                  description: Date/time when the order was canceled in the source system.
              required:
                - canceledReason
                - sourceCanceledOn
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /orders/{orderId}/fulfillments:
    get:
      tags:
        - Fulfillments
      description: >-
        Retrieve all fulfillment records for an order. Records are not
        individually retrievable and this is the only endpoint available to read
        these resources.
      summary: List order fulfillments
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fulfillment List'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    post:
      tags:
        - Fulfillments
      description: >-
        Notify Corso of a fulfillment associated with an order. This permits
        tracking and verification of the status of an order that a customer
        might need assistance with.
      summary: Create a fulfillment
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceFulfillmentId:
                  type: string
                  example: ACME-FULFILL-439823
                  description: The ID of the fulfillment, as recorded in merchant systems.
                shippingWeightGrams:
                  type: number
                  description: The weight of the fulfillment in grams
                fulfillmentLocationId:
                  type: number
                  description: The Corso ID of the location the order is fulfilled from.
                deliveredOn:
                  type: string
                  format: date-time
                  example: '2022-01-01T17:32:28Z'
                  description: ' Date/time when the fulfillment was delivered.'
                trackingInfoCompany:
                  type: string
                  description: The courier used to ship the fulfillment.
                  example: USPS
                trackingInfoNumber:
                  type: string
                  description: The tracking number for the fulfillment.
                  example: UPS-12345
                trackingInfoUrl:
                  type: string
                  format: url
                  description: The URL to track the fulfillment.
                  example: >-
                    https://www.ups.com/track?loc=en_US&tracknum=1Z12345E0291980793
                estimatedDeliveryOn:
                  type: string
                  format: date-time
                  description: >-
                    Date/time when the fulfillment is estimated to be delivered
                    on.
                shipmentStatus:
                  type: string
                  description: The status of the shipment.
                  example: in_transit
                inTransitOn:
                  type: string
                  format: date-time
                  description: Date/time when the fulfillment was shipped.
                sourceCreatedOn:
                  type: string
                  format: date-time
                  example: '2022-01-01T17:32:28Z'
                  description: >-
                    Date/time when the fulfillment was created in the source
                    system.
              required:
                - sourceFulfillmentId
                - fulfillmentLocationId
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fulfillments'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /orders/{orderId}/line-items:
    post:
      tags:
        - Line Items
      description: >-
        Add a line item to an existing order, reflecting a change in the order
        itself.
      summary: Create a line item
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceLineItemId:
                  type: string
                  description: The line item ID (from the source system).
                  example: '990986'
                productId:
                  type: string
                  description: The product ID for the line item (from the source system).
                  example: pro-33320
                variantId:
                  type: string
                  description: >-
                    The variant ID for the line item (from the source system).
                    For the line item that represents the Corso Green Shipping
                    Product (if purchased on the order), this should match the
                    corresponding variant ID stored by Corso in our system, so
                    that we can identify the order as protected.
                  example: var-4569876332
                name:
                  type: string
                  description: >-
                    The line item name, typically the value shown to the
                    customer representing the product/variant combination
                    purchased.
                  example: 'Shorts - color: blue, size: small'
                quantity:
                  type: number
                  description: The quantity purchased for the line item.
                  example: 1
                sku:
                  type: string
                  description: The SKU of product/variant of the line item.
                  example: ITEM-12345
                tax:
                  type: number
                  description: Any tax applied to the line item.
                  example: 1.23
                  format: currency
                vendor:
                  type: string
                  description: The vendor of the line item
                  example: Nike
                price:
                  type: number
                  description: The price of the line item
                  example: 129.53
                  format: currency
              required:
                - sourceLineItemId
                - productId
                - variantId
                - name
                - quantity
                - sku
                - tax
                - price
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Line Items'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /orders/{orderId}/line-items/{lineItemId}:
    get:
      tags:
        - Line Items
      description: Get a single line item from an order.
      summary: Get a line Item
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 12345
          description: The Corso ID for a Line Item associated with an order.
          name: lineItemId
          in: path
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Line Items'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    delete:
      tags:
        - Line Items
      description: >-
        Remove a line item from an order. Because line items are considered
        immutable via the API, an edit is performed as a removal followed by the
        creation of a new line item.
      summary: Remove a line item
      parameters:
        - schema:
            type: number
            nullable: true
          required: true
          example: 12345
          description: The Corso ID for a Line Item associated with an order.
          name: lineItemId
          in: path
        - schema:
            type: number
            nullable: true
          required: true
          example: 428334
          description: The Corso ID for an order record.
          name: orderId
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceCanceledOn:
                  type: string
                  format: date-time
                  example: '2022-01-01T17:32:28Z'
                  description: Date/time when the order was canceled in Corso systems.
              required:
                - sourceCanceledOn
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Line Items'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
