Spreadshirt Orders API

openapi: 3.2.0
info:
  version: 0.1.0
  title: Spreadconnect fulfillment service REST Orders API
  contact:
    name: Spreadconnect
    email: business@spreadconnect.app
    url: https://www.spreadshop.com/spreadconnect
  x-logo:
    url: https://assets.spod.com/merea/spreadconnect-logo-black.svg
  description: 'With this API you can create products and place orders in the Spreadconnect system.

    This gives you the opportunity to connect any shop system with Spreadconnect.'
  termsOfService: https://faq.spod.com/hc/en-us/articles/360020630280
servers:
- url: https://api.spreadconnect.app
tags:
- name: Orders
  description: 'There are different ways to place an order in Spreadconnect REST API.

    You can choose a simple way, where you have to send just one request or you can use a more complex way,

    with more control over the workflow.


    Spreadconnect API - order workflowWorkflowmore easiermore controlwith preferred shipping typeand state CONFIRMEDCreate orderonly with mandatory fieldsCreate orderGet available shipping typesSet shipping typeConfirm order'
paths:
  /orders:
    post:
      operationId: createOrder
      summary: Create an order
      description: 'Place a new order in the API. You can choose the simple way and set the shipping type and the confirmed state in one request. Or you can create the order first and set the shipping type and the confirmed state later. It is also possible to mix both ways and set the shipping type direct and confirm later.

        You can order existing articles, or one-time items, which are created just for the respective order, and deleted afterwards. You need to add at least one orderItem or oneTimeItem.'
      tags:
      - Orders
      security:
      - access_token: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrder'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrder'
        '422':
          description: Order payload invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orders/{orderId}:
    put:
      operationId: updateOrder
      summary: Update order
      description: update order
      tags:
      - Orders
      security:
      - access_token: []
      parameters:
      - in: path
        name: orderId
        description: spreadconnect order id
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrder'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrder'
        '404':
          description: Order not found
        '422':
          description: Order payload invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: getOrder
      summary: Get a single order
      description: get a specific order with all details
      tags:
      - Orders
      security:
      - access_token: []
      parameters:
      - in: path
        name: orderId
        description: spreadconnect order id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrder'
        '404':
          description: Order not found
  /orders/{orderId}/shippingTypes:
    get:
      operationId: getShippingTypes
      summary: Get available shipping types
      description: get a list with all possible shipping types for this order
      tags:
      - Orders
      security:
      - access_token: []
      parameters:
      - in: path
        name: orderId
        description: spreadconnect order id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailableShippingType'
        '404':
          description: Order not found
  /orders/{orderId}/shippingType:
    post:
      operationId: setShippingType
      summary: Set shipping type
      description: Set a specific shipping type
      tags:
      - Orders
      security:
      - access_token: []
      parameters:
      - in: path
        name: orderId
        description: spreadconnect order id
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  example: '29'
      responses:
        '200':
          description: OK
        '404':
          description: Order or Shipping Type not found
  /orders/{orderId}/confirm:
    post:
      operationId: confirmOrder
      summary: Confirm order
      description: Try to confirm an order. To do it, it's necessary to set a shipping type before.
      tags:
      - Orders
      security:
      - access_token: []
      parameters:
      - in: path
        name: orderId
        description: spreadconnect order id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
        '400':
          description: Order couldn't be confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
  /orders/{orderId}/cancel:
    post:
      operationId: cancelOrder
      summary: Cancel order
      description: Try to cancel an order. It is not possible to cancel orders that have already been sent or are already in production internally.
      tags:
      - Orders
      security:
      - access_token: []
      parameters:
      - in: path
        name: orderId
        description: spreadconnect order id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
        '400':
          description: Order could not be cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found
  /orders/{orderId}/shipments:
    get:
      operationId: getShipments
      summary: Get shipments
      description: get a list with all shipments for this order
      tags:
      - Orders
      security:
      - access_token: []
      parameters:
      - in: path
        name: orderId
        description: spreadconnect order id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shipment'
        '404':
          description: Order not found
components:
  schemas:
    Price:
      type: object
      description: price
      required:
      - amount
      properties:
        amount:
          type: number
          description: total amount, with vat or sales tax
          example: 21.56
          minimum: 0
        taxRate:
          type: number
          description: included vat rate in percent, only for tax type VAT
          example: 19
          minimum: 0
        taxAmount:
          type: number
          description: included sales tax, only for tax type SALETAX
          example: 12.45
          minimum: 0
        currency:
          type: string
          description: currency iso code
          example: USD
    CreateOrderItem:
      type: object
      required:
      - sku
      - quantity
      - customerPrice
      properties:
        sku:
          type: string
          description: stock keeping unit id from spreadconnect
          example: P1026247707A12S5
        quantity:
          type: integer
          description: quantity of items
          default: 1
        externalOrderItemReference:
          type: string
          description: external order item reference from merchant (you)
          example: '12810092145'
        customerPrice:
          description: customer price for item with quantity n
          allOf:
          - $ref: '#/components/schemas/CustomerPrice'
    Address:
      type: object
      description: physical mailing address
      required:
      - lastName
      - street
      - city
      - country
      - zipCode
      properties:
        company:
          type: string
          description: company name
          example: Example Ltd.
        firstName:
          type: string
          description: first name
          example: Joshua
        lastName:
          type: string
          description: last name
          example: Anderson
        street:
          type: string
          description: street
          example: 1572 Roseytown Rd
        streetAnnex:
          example: 2nd Floor
          description: street annex, optional
          type: string
        city:
          example: Greensburg
          description: city name
          type: string
        country:
          type: string
          description: country code, is the ISO 3166-1 alpha-2 code of the country to deliver to, e.g. 'DE' or 'US'.
          example: US
        state:
          type: string
          description: 'state code, is the country-specific 2-letter upper-case, e.g. AL for Alabama in the USA

            This field is required when delivering to the USA or Canada

            '
          example: AL
        zipCode:
          example: '15601'
          description: zip code, for some countries optional
          type: string
    CreateOrder:
      type: object
      description: payload for a new order
      required:
      - externalOrderReference
      - orderItems
      - shipping
      - phone
      - email
      properties:
        orderItems:
          type: array
          description: order items
          items:
            $ref: '#/components/schemas/CreateOrderItem'
        oneTimeItems:
          $ref: '#/components/schemas/OneTimeItems'
        shipping:
          type: object
          description: shipping informations
          required:
          - address
          - customerPrice
          properties:
            address:
              description: shipping address
              allOf:
              - $ref: '#/components/schemas/Address'
            fromAddress:
              description: return to sender (RTS) address
              allOf:
              - $ref: '#/components/schemas/Address'
            preferredType:
              type: string
              description: preferred shipping type
              enum:
              - STANDARD
              - PREMIUM
              - EXPRESS
            customerPrice:
              description: customer price for shipping
              allOf:
              - $ref: '#/components/schemas/CustomerPrice'
        billingAddress:
          description: billing address, if not set, we will use the shipping address
          allOf:
          - $ref: '#/components/schemas/Address'
        phone:
          type: string
          description: Phone used for the communication with the customer.
          example: +49 1520 1234567
        email:
          type: string
          description: Email used for the communication with the customer.
          example: joshua.anders@protonmail.ch
        externalOrderReference:
          type: string
          description: external order reference from merchant (you)
          example: '1722995712'
        externalOrderName:
          type: string
          description: external order name from merchant (you)
          example: ORDER-12
        state:
          type: string
          description: order state
          example: CONFIRMED
          enum:
          - NEW
          - CONFIRMED
        customerTaxType:
          type: string
          description: tax type, salestax or vat
          enum:
          - SALESTAX
          - VAT
          - NOT_TAXABLE
        origin:
          type: string
          description: optional origin field
    AvailableShippingType:
      type: object
      description: shipping type with price
      allOf:
      - $ref: '#/components/schemas/ShippingType'
      properties:
        price:
          $ref: '#/components/schemas/Price'
    OneTimeItems:
      type: array
      description: items which are created only for this order, and deleted afterwards.
      items:
        type: object
        properties:
          quantityItems:
            type: array
            description: Each quantity item represents the relationship between an article variant and the quantities required for the variant
            items:
              type: object
              properties:
                quantity:
                  type: number
                  required: true
                sizeId:
                  type: number
                  required: true
                appearanceId:
                  required: true
          configurations:
            type: array
            description: product
            items:
              type: object
              required:
              - image
              - view
              properties:
                image:
                  type: object
                  properties:
                    url:
                      type: string
                      example: https://link.to.image
                    designId:
                      type: string
                      example: '1231'
                view:
                  type: string
                  enum:
                  - FRONT
                  - BACK
                  - LEFT
                  - RIGHT
                  - HOOD_LEFT
                  - HOOD_RIGHT
                hotspot:
                  type: string
                  enum:
                  - FULL_FRONT
                  - MEDIUM_FRONT
                  - LEFT_CHEST
                  - RIGHT_CHEST
                  - FULL_BACK
                  - MEDIUM_BACK
                  - BACK_COLLAR
                  - RIGHT
                  - LEFT
                  - CENTER_CHEST
                  example: LEFT_CHEST
          productTypeId:
            type: number
            required: true
          externalOrderItemReference:
            type: string
          customerPricePerItem:
            allOf:
            - $ref: '#/components/schemas/CustomerPrice'
    GetOrderItem:
      type: object
      properties:
        orderItemReference:
          type: integer
          description: spreadconnect order item reference
          example: 55000001
        externalOrderItemReference:
          type: string
          description: external order item reference from merchant (you)
          example: '12810092145'
        state:
          type: string
          description: order item state
          enum:
          - NEW
          - CHECKED
          - CANCELLED
          - PRODUCTION_ISSUE
          - IN_PRODUCTION
          - SENT
        sku:
          type: string
          description: stock keeping unit id from spreadconnect
          example: P1026247707A12S5
        quantity:
          type: integer
          description: item quantity
          default: 1
        price:
          description: item price for item with quantity n
          allOf:
          - $ref: '#/components/schemas/Price'
        customerPrice:
          description: customer price for item with quantity n
          allOf:
          - $ref: '#/components/schemas/CustomerPrice'
    ErrorResponse:
      type: object
      description: error response
      properties:
        orderId:
          type: number
          description: spreadconnect order id, can be null, if order not created
        reason:
          type: string
          description: error reason
    CustomerPrice:
      type: object
      description: customer price
      required:
      - amount
      properties:
        amount:
          type: number
          description: total amount, with vat or sales tax
          example: 21.56
          minimum: 0
        currency:
          type: string
          description: currency iso code
          example: USD
    ShippingType:
      type: object
      description: shipping type with id, name and description
      properties:
        id:
          type: string
          description: shipping type id, needed for set shipping type
          example: '29'
        company:
          type: string
          description: shipping company such as DHL, UPS, DPD, USPS, DHL Express, FedEx, Post AT, Deutsche Post
          example: DHL
        name:
          type: string
          example: International Standard
        description:
          type: string
          example: No tracking provided. May be subject to import taxes, customs, and duties upon delivery.
    GetOrder:
      type: object
      properties:
        id:
          type: integer
          description: order id from spreadconnect
          example: 123
        orderReference:
          type: integer
          description: order reference from spreadconnect, can be changed after order updates
          example: 5550000
        externalOrderReference:
          type: string
          description: external order reference from merchant (you)
          example: '1722995712'
        externalOrderName:
          type: string
          description: external order name from merchant (you)
          example: ORDER-12
        state:
          type: string
          description: order state
          enum:
          - NEW
          - CONFIRMED
          - PROCESSED
          - CANCELLED
        orderItems:
          type: array
          description: order items
          items:
            $ref: '#/components/schemas/GetOrderItem'
        shipping:
          type: object
          description: shipping information
          properties:
            address:
              description: shipping address
              allOf:
              - $ref: '#/components/schemas/Address'
            fromAddress:
              description: return to sender (RTS) address
              allOf:
              - $ref: '#/components/schemas/Address'
            type:
              description: shipping type
              allOf:
              - $ref: '#/components/schemas/ShippingType'
            price:
              description: shipping price
              allOf:
              - $ref: '#/components/schemas/Price'
            customerPrice:
              description: shipping price for your customer
              allOf:
              - $ref: '#/components/schemas/CustomerPrice'
        billingAddress:
          description: billing address
          allOf:
          - $ref: '#/components/schemas/Address'
        phone:
          type: string
          description: Phone used for the communication with the customer.
          example: +49 1520 1234567
        email:
          type: string
          description: Email used for the communication with the customer.
          example: joshua.anders@protonmail.ch
        price:
          description: price for the complete order
          allOf:
          - $ref: '#/components/schemas/Price'
        taxType:
          type: string
          description: tax type, salestax or vat
          enum:
          - SALESTAX
          - VAT
          - NOT_TAXABLE
        customerTaxType:
          type: string
          description: tax type, salestax or vat
          enum:
          - SALESTAX
          - VAT
          - NOT_TAXABLE
    Shipment:
      type: object
      properties:
        id:
          type: integer
          description: shipment id
        orderId:
          type: integer
          description: spreadconnect order id
        orderReference:
          type: integer
          description: order reference from spreadconnect, can be changed after order updates
        externalOrderReference:
          type: string
          description: external order reference from merchant (you)
        orderItemReferences:
          type: array
          description: spreadconnect order item references
          items:
            type: integer
        externalOrderItemReferences:
          type: array
          description: external order item references
          items:
            type: string
        shipping:
          type: object
          description: shipment shipping information
          properties:
            address:
              $ref: '#/components/schemas/Address'
            type:
              $ref: '#/components/schemas/ShippingType'
            price:
              $ref: '#/components/schemas/Price'
        tracking:
          type: array
          description: tracking information for shipment
          items:
            type: object
            properties:
              code:
                type: string
                description: tracking code
              url:
                type: string
                description: tracking url
        closedDate:
          type: string
          description: ready for shipment date
        sentDate:
          type: string
          description: sent date
  securitySchemes:
    access_token:
      type: apiKey
      in: header
      name: X-SPOD-ACCESS-TOKEN
      description: It's necessary to have an authentication token from Spreadconnect. You can generate this token in your Spreadconnect web application. You have to send this token as a header parameter in each request.