SPOD Shipping API

openapi: 3.0.3
info:
  title: SPOD (Spreadconnect) Fulfillment REST API
  version: '1.0'
  description: >-
    REST API for SPOD (Spreadshirt Print-On-Demand), now branded Spreadconnect.
    Create customizable articles from designs, place and manage print-on-demand
    orders, choose shipping types and track shipments, browse the catalog of
    product types, check stock, and subscribe to webhook notifications for
    article, order, and shipment events. All requests are authenticated with a
    per-account API access token sent in the X-SPOD-ACCESS-TOKEN header. This
    document is an API Evangelist reference grounded in SPOD's published
    OpenAPI and developer documentation; verify request/response schemas against
    the live docs before production use.
  contact:
    name: SPOD
    url: https://www.spod.com
    email: business@spod.com
  termsOfService: https://faq.spod.com/hc/en-us/articles/360020630280
servers:
- url: https://rest.spod.com
  description: Production
- url: https://rest.spreadconnect-staging.app
  description: Staging / test environment
security:
- access_token: []
tags:
- name: Common
- name: Articles
- name: Orders
- name: Shipping
- name: Product Types
- name: Stock
- name: Subscriptions
paths:
  /authentication:
    get:
      tags:
      - Common
      operationId: authenticationInfo
      summary: Verify the API access token
      description: Returns authentication information for the supplied access token, used to confirm credentials are valid.
      responses:
        '200':
          description: Authentication information.
        '401':
          description: Missing or invalid access token.
  /articles:
    get:
      tags:
      - Articles
      operationId: getArticles
      summary: List articles
      description: Retrieve all articles for the account, paginated.
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: A paginated list of articles.
    post:
      tags:
      - Articles
      operationId: createArticle
      summary: Create an article
      description: Create a new customizable article by combining a design with a product type and view.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleRequest'
      responses:
        '201':
          description: The created article.
  /articles/{articleId}:
    get:
      tags:
      - Articles
      operationId: getArticle
      summary: Get an article
      parameters:
      - $ref: '#/components/parameters/ArticleId'
      responses:
        '200':
          description: The requested article.
        '404':
          description: Article not found.
    delete:
      tags:
      - Articles
      operationId: deleteArticle
      summary: Delete an article
      parameters:
      - $ref: '#/components/parameters/ArticleId'
      responses:
        '204':
          description: Article deleted.
  /orders:
    post:
      tags:
      - Orders
      operationId: createOrder
      summary: Create an order
      description: >-
        Create a new order. In the simple flow you send a preferred shipping
        type and state CONFIRMED in one request; in the controlled flow you
        create the order with mandatory fields, then set the shipping type and
        confirm it in later requests.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: The created order.
  /orders/{orderId}:
    get:
      tags:
      - Orders
      operationId: getOrder
      summary: Get an order
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The requested order.
        '404':
          description: Order not found.
    put:
      tags:
      - Orders
      operationId: updateOrder
      summary: Update an order
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '200':
          description: The updated order.
  /orders/{orderId}/confirm:
    post:
      tags:
      - Orders
      operationId: confirmOrder
      summary: Confirm an order
      description: Confirm an order so it enters production. A confirmed order can no longer be edited.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: The confirmed order.
  /orders/{orderId}/cancel:
    post:
      tags:
      - Orders
      operationId: cancelOrder
      summary: Cancel an order
      description: Attempt to cancel an order. Cancellation only succeeds while the order has not yet entered production.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Cancellation result.
  /orders/{orderId}/shippingTypes:
    get:
      tags:
      - Shipping
      operationId: getShippingTypes
      summary: Get available shipping types for an order
      description: List the shipping types available for the order, including price and estimated delivery time.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Available shipping types.
  /orders/{orderId}/shippingType:
    post:
      tags:
      - Shipping
      operationId: setShippingType
      summary: Set the shipping type for an order
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shippingType:
                  type: integer
                  description: The identifier of the chosen shipping type.
      responses:
        '200':
          description: The order with the shipping type set.
  /orders/{orderId}/shipments:
    get:
      tags:
      - Shipping
      operationId: getShipments
      summary: Get shipments for an order
      description: Retrieve the shipment records for an order, including carrier and tracking details once dispatched.
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Shipment records for the order.
  /productTypes:
    get:
      tags:
      - Product Types
      operationId: getProductTypes
      summary: List product types
      description: List the catalog of available product types (article types) that articles can be built from.
      responses:
        '200':
          description: A list of product types.
  /productTypes/{productTypeId}:
    get:
      tags:
      - Product Types
      operationId: getProductType
      summary: Get a product type
      description: Retrieve a product type with its sizes, colors, views, and printable areas.
      parameters:
      - name: productTypeId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested product type.
        '404':
          description: Product type not found.
  /stock:
    get:
      tags:
      - Stock
      operationId: getStocks
      summary: List stock for all variants
      description: Retrieve inventory availability across all product variants.
      responses:
        '200':
          description: Stock across variants.
  /stock/{sku}:
    get:
      tags:
      - Stock
      operationId: getStock
      summary: Get stock for a SKU
      parameters:
      - name: sku
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stock for the given SKU.
        '404':
          description: SKU not found.
  /subscriptions:
    get:
      tags:
      - Subscriptions
      operationId: getSubscriptions
      summary: List subscriptions
      description: List the account's active webhook subscriptions.
      responses:
        '200':
          description: A list of subscriptions.
    post:
      tags:
      - Subscriptions
      operationId: createSubscription
      summary: Create a subscription
      description: >-
        Register a webhook subscription. Notifications are delivered by POST
        following an at-least-once model and must be acknowledged with a 202
        status, a response within 8 seconds, and the payload [accepted]. If a
        secret is set, notifications carry an X-SPRD-SIGNATURE header (a Base64
        SHA256 HMAC over the request body) for authenticity verification.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '201':
          description: The created subscription.
  /subscriptions/{subscriptionId}:
    delete:
      tags:
      - Subscriptions
      operationId: deleteSubscription
      summary: Delete a subscription
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Subscription deleted.
  /orders/{orderId}/simulate/order-cancelled:
    post:
      tags:
      - Subscriptions
      operationId: simulateOrderCancelledEvent
      summary: Simulate an Order.cancelled event
      description: Trigger a test Order.cancelled webhook notification for the given order (test/staging use).
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Simulated event dispatched.
  /orders/{orderId}/simulate/order-processed:
    post:
      tags:
      - Subscriptions
      operationId: simulateOrderProcessedEvent
      summary: Simulate an Order.processed event
      description: Trigger a test Order.processed webhook notification for the given order (test/staging use).
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Simulated event dispatched.
  /orders/{orderId}/simulate/shipment-sent:
    post:
      tags:
      - Subscriptions
      operationId: simulateShipmentSentEvent
      summary: Simulate a Shipment.sent event
      description: Trigger a test Shipment.sent webhook notification for the given order (test/staging use).
      parameters:
      - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Simulated event dispatched.
components:
  securitySchemes:
    access_token:
      type: apiKey
      in: header
      name: X-SPOD-ACCESS-TOKEN
      description: >-
        Per-account API access token generated in the SPOD / Spreadconnect web
        application. Send it as a header on every request.
  parameters:
    ArticleId:
      name: articleId
      in: path
      required: true
      schema:
        type: integer
    OrderId:
      name: orderId
      in: path
      required: true
      schema:
        type: integer
  schemas:
    ArticleRequest:
      type: object
      description: Article creation payload. Refer to the live SPOD docs for the full schema.
      properties:
        title:
          type: string
        description:
          type: string
        productTypeId:
          type: integer
        configurations:
          type: array
          items:
            type: object
    OrderRequest:
      type: object
      description: Order payload. Refer to the live SPOD docs for the full schema.
      properties:
        orderItems:
          type: array
          items:
            type: object
        shipping:
          type: object
        billingAddress:
          type: object
        state:
          type: string
          enum:
          - NEW
          - CONFIRMED
    SubscriptionRequest:
      type: object
      description: Webhook subscription payload.
      properties:
        eventType:
          type: string
          description: The event to subscribe to (for example Article.added, Order.processed, Order.cancelled, Shipment.sent).
        url:
          type: string
          format: uri
          description: The endpoint that will receive POST notifications.
        secret:
          type: string
          description: Optional secret used to compute the X-SPRD-SIGNATURE HMAC.