VSCO Orders API

openapi: 3.0.0
info:
  title: VSCO Workspace Brands Orders API
  termsOfService: https://terms-of-service.vsco.page/
  description: This API is for interacting with a single Studio using <a href="https://workspace.vsco.co/settings/api" target="_blank">an API Key</a>.
  contact:
    name: VSCO Workspace Support
    url: https://help.workspace.vsco.co/
    email: workspace-support@vsco.co
  version: v2.0.0
  x-logo:
    url: https://workspace.vsco.co/static/Images/Public/Logo.Black.vsco.svg
    altText: VSCO Workspace
servers:
- url: https://tave.io/v2
  description: Legacy Táve API production environment
- url: https://workspace.vsco.co/api/v2
  description: Workspace API production environment
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Orders
paths:
  /job/{jobId}/order:
    get:
      summary: List of orders on a given Job
      operationId: listResourceJobOrders
      x-entity: Invoice
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/jobIdInPath'
      - name: sortBy
        in: query
        description: Sort items in the collection by the given property.
        schema:
          title: Sort objects by properties
          type: string
          anyOf:
          - title: id
            enum:
            - id
            - id asc
            - id desc
          - title: modified
            enum:
            - modified
            - modified asc
            - modified desc
          - title: created
            enum:
            - created
            - created asc
            - created desc
          - title: name
            enum:
            - name
            - name asc
            - name desc
          - title: sortPosition
            enum:
            - sortPosition
            - sortPosition asc
            - sortPosition desc
          default: sortPosition
      responses:
        '200':
          description: Orders list response for a given Job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobOrderCollection'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    post:
      summary: Create an order on a given job.
      operationId: createResourceJobOrder
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/jobIdInPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '201':
          description: Order creation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
  /order:
    get:
      summary: Get a list of orders
      operationId: listResourceOrder
      x-entity: Invoice
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - name: sortBy
        in: query
        description: Sort items in the collection by the given property.
        schema:
          title: Sort objects by properties
          type: string
          anyOf:
          - title: id
            enum:
            - id
            - id asc
            - id desc
          - title: modified
            enum:
            - modified
            - modified asc
            - modified desc
          - title: created
            enum:
            - created
            - created asc
            - created desc
          - title: name
            enum:
            - name
            - name asc
            - name desc
          - title: sortPosition
            enum:
            - sortPosition
            - sortPosition asc
            - sortPosition desc
          default: sortPosition
      responses:
        '200':
          description: Order list response.
          content:
            application/json:
              schema:
                allOf:
                - properties:
                    type:
                      enum:
                      - order-collection
                    items:
                      title: Orders
                      type: array
                      items:
                        $ref: '#/components/schemas/Order'
                - $ref: '#/components/schemas/List'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
  /order/{id}:
    get:
      summary: Get a specific Order
      operationId: getResourceOrder
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/idInPath'
      responses:
        '200':
          description: Successfully retrieve a Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
    put:
      summary: Update a specific Order
      operationId: updateResourceOrder
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/idInPath'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
      responses:
        '200':
          description: Order response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/validationError'
        '429':
          $ref: '#/components/responses/tooManyRequestsError'
components:
  parameters:
    pageSize:
      name: pageSize
      in: query
      description: Number of results per page to return in the collection.
      schema:
        type: integer
        minimum: 10
        maximum: 100
        default: 100
    page:
      name: page
      in: query
      description: The page of results to return.
      schema:
        type: integer
        default: 1
        minimum: 1
    jobIdInPath:
      name: jobId
      in: path
      schema:
        $ref: '#/components/schemas/Id'
    idInPath:
      name: id
      in: path
      description: ULID to perform an action on.
      schema:
        $ref: '#/components/schemas/Id'
  responses:
    validationError:
      description: 'Validation error response. Check the `info.errors` property in the

        response for more details.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorValidation'
    tooManyRequestsError:
      description: Exceeded request quota, see Retry-After header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    OrderItem:
      title: Order Item
      type: object
      required:
      - name
      properties:
        id:
          $ref: '#/components/schemas/Id'
        created:
          $ref: '#/components/schemas/ServerTimestamp'
        modified:
          $ref: '#/components/schemas/ServerTimestamp'
        hidden:
          $ref: '#/components/schemas/IsHidden'
        orderId:
          $ref: '#/components/schemas/Id'
        productId:
          allOf:
          - $ref: '#/components/schemas/Id'
          nullable: true
        name:
          type: string
          minLength: 1
          maxLength: 128
        descriptionHtml:
          type: string
          maxLength: 16777215
          nullable: true
        baseConfiguration:
          type: array
          nullable: true
          readOnly: true
          items:
            $ref: '#/components/schemas/ProductConfiguration'
        configuration:
          type: array
          nullable: true
          readOnly: true
          items:
            $ref: '#/components/schemas/ProductConfiguration'
        basePricePerUnit:
          $ref: '#/components/schemas/MoneyAmount'
        pricePerUnit:
          $ref: '#/components/schemas/MoneyAmount'
        baseCostPerUnit:
          $ref: '#/components/schemas/MoneyAmount'
        costPerUnit:
          $ref: '#/components/schemas/MoneyAmount'
        units:
          type: number
          format: float
        taxable:
          type: boolean
        discount:
          type: boolean
        discountKind:
          type: string
          enum:
          - amount
          - percent
          default: amount
        selectability:
          type: string
          enum:
          - required
          - suggested
          - optional
          default: required
        selected:
          type: boolean
        children:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/OrderItem'
    MoneyAmount:
      title: Numeric representing an amount in the studio's currency
      type: integer
      minimum: -99999999999
      maximum: 99999999999
      example: 200
    NullableDate:
      title: A date that could be null instead
      description: 'A date string consisting of year, month and day in the timezone of the

        event if specified or the studio.'
      type: string
      format: date
      nullable: true
      example: '2020-04-10'
    JobOrderCollection:
      allOf:
      - properties:
          type:
            enum:
            - joborder-collection
          items:
            title: Order
            type: array
            items:
              $ref: '#/components/schemas/Order'
      - $ref: '#/components/schemas/List'
    ProductConfiguration:
      title: Product Configuration
      type: object
      required:
      - name
      - affectsPrice
      - kind
      - value
      properties:
        id:
          allOf:
          - description: If this option was created in VSCO Workspace, it will have an ID. If this order was imported, it may not.
          - $ref: '#/components/schemas/NullableId'
        name:
          type: string
        affectsPrice:
          type: boolean
        kind:
          type: string
          enum:
          - AddOn
          - Option
        value:
          type: string
        unitCost:
          allOf:
          - nullable: true
          - $ref: '#/components/schemas/MoneyAmount'
        unitPrice:
          allOf:
          - nullable: true
          - $ref: '#/components/schemas/MoneyAmount'
    Error:
      description: An error.
      type: object
      properties:
        type:
          description: A namespace URI uniquely identifying the error type.
          type: string
          enum:
          - unknown
          - quota-limit
          - not-implemented
        title:
          description: A short description of the error encountered.
          type: string
          example: Bad Request
        detail:
          description: A longer description of of the error encountered.
          type: string
          example: There was a problem with your request. Please see `info` for more information.
        status:
          description: The HTTP status code associated with this error.
          type: integer
          example: 400
    PositiveMoneyAmount:
      title: Positive numeric representing an amount in the studio's currency
      type: integer
      minimum: 0
      maximum: 99999999999
    Invoice:
      title: Invoice
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        created:
          $ref: '#/components/schemas/ServerTimestamp'
        modified:
          $ref: '#/components/schemas/ServerTimestamp'
        hidden:
          $ref: '#/components/schemas/IsHidden'
        status:
          type: string
          enum:
          - draft
          - open
          - paid-in-full
          - voided
          readOnly: true
        customNumber:
          type: string
          maxLength: 16
          readOnly: true
        orderId:
          allOf:
          - readOnly: true
          - $ref: '#/components/schemas/Id'
        title:
          type: string
          description: An auto-generated title of the invoice
          nullable: true
          readOnly: true
        dueDate:
          $ref: '#/components/schemas/NullableDate'
        recipientId:
          $ref: '#/components/schemas/NullableId'
        promisedArrival:
          $ref: '#/components/schemas/NullableDate'
        response:
          type: string
          nullable: true
          maxLength: 16777215
        referenceCode:
          type: string
          readOnly: true
          maxLength: 11
        total:
          allOf:
          - readOnly: true
          - $ref: '#/components/schemas/MoneyAmount'
    NullableId:
      title: Entity Identifier that might be null instead
      description: A ULID entity identifier that is nullable.
      type: string
      format: ulid
      nullable: true
      example: 01fqcr215r79p3h19crqbpzwzh
    ResourceType:
      title: Resource Type
      description: The type of resource represented.
      type: string
      example: resource-type
    OrderConfiguration:
      title: Order Configuration
      type: object
      properties:
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        preTaxDiscount:
          type: object
          readOnly: true
          nullable: true
          properties:
            fixedAmount:
              allOf:
              - nullable: true
              - $ref: '#/components/schemas/PositiveMoneyAmount'
            percentageAmount:
              allOf:
              - nullable: true
              - $ref: '#/components/schemas/PositiveMoneyAmount'
            percentage:
              nullable: true
              type: integer
              minimum: 0
              maximum: 100
              multipleOf: 0.001
        afterTaxDiscount:
          type: object
          readOnly: true
          nullable: true
          properties:
            fixedAmount:
              allOf:
              - nullable: true
              - $ref: '#/components/schemas/PositiveMoneyAmount'
            percentageAmount:
              allOf:
              - nullable: true
              - $ref: '#/components/schemas/PositiveMoneyAmount'
            percentage:
              type: integer
              minimum: 0
              maximum: 100
              multipleOf: 0.001
        taxGroupId:
          $ref: '#/components/schemas/NullableId'
        tax1:
          title: Tax Line
          description: These values are computed when a taxGroupId is set on the order
          type: object
          readOnly: true
          nullable: true
          properties:
            taxRateId:
              $ref: '#/components/schemas/NullableId'
            isInclusive:
              type: boolean
              default: false
            name:
              type: string
            rate:
              type: number
              minimum: 0
              maximum: 1
              multipleOf: 0.0001
            amount:
              $ref: '#/components/schemas/PositiveMoneyAmount'
        tax2:
          $ref: '#/components/schemas/OrderConfiguration/properties/tax1'
        tax3:
          $ref: '#/components/schemas/OrderConfiguration/properties/tax1'
        taxCombined:
          allOf:
          - title: Combined Tax Line
            description: This is a summary of all tax lines if the tax is configured to combine separate tax lines into a single line on orders and invoices
          - $ref: '#/components/schemas/OrderConfiguration/properties/tax1'
        taxIsCompounding:
          type: boolean
          description: Rarely, certain taxes are compounded one after the other, aka "tax the tax"
          readOnly: true
          default: false
        subtotal:
          type: object
          readOnly: true
          properties:
            amount:
              $ref: '#/components/schemas/PositiveMoneyAmount'
            taxable:
              $ref: '#/components/schemas/PositiveMoneyAmount'
            nonTaxable:
              $ref: '#/components/schemas/PositiveMoneyAmount'
        total:
          allOf:
          - readOnly: true
          - $ref: '#/components/schemas/PositiveMoneyAmount'
    ServerTimestamp:
      title: Server Timestamp
      description: A server timestamp (always in UTC)
      type: string
      format: date-time
      readOnly: true
      example: '2020-08-01T17:32:32Z'
    Order:
      title: Order
      allOf:
      - $ref: '#/components/schemas/OrderConfiguration'
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/Id'
          created:
            $ref: '#/components/schemas/ServerTimestamp'
          modified:
            $ref: '#/components/schemas/ServerTimestamp'
          hidden:
            $ref: '#/components/schemas/IsHidden'
          jobId:
            $ref: '#/components/schemas/Id'
          recipientId:
            $ref: '#/components/schemas/NullableId'
          customNumber:
            type: string
            maxLength: 16
            readOnly: true
            nullable: true
          dueDate:
            allOf:
            - description: Auto create a single invoice for this order using this due date
              writeOnly: true
            - $ref: '#/components/schemas/NullableDate'
          name:
            type: string
            nullable: true
          title:
            type: string
            description: The name or auto-generated title of the order
            nullable: true
            readOnly: true
          referenceCode:
            type: string
            readOnly: true
            maxLength: 11
          status:
            type: string
            enum:
            - draft
            - open
            - paid-in-full
            - completed
            - voided
            readOnly: true
          bookedElectronically:
            type: boolean
            readOnly: true
            default: false
          bookedFromQuote:
            type: boolean
            readOnly: true
            default: false
          bookedOn:
            allOf:
            - readOnly: true
            - $ref: '#/components/schemas/NullableDate'
          balance:
            allOf:
            - readOnly: true
            - $ref: '#/components/schemas/PositiveMoneyAmount'
          paymentTermsId:
            $ref: '#/components/schemas/NullableId'
          paymentTermsName:
            type: string
            readOnly: true
          paymentAllocations:
            readOnly: true
            type: array
            items:
              $ref: '#/components/schemas/PaymentAllocation'
          invoices:
            readOnly: true
            type: array
            items:
              $ref: '#/components/schemas/Invoice'
    IsHidden:
      title: Hidden attribute
      description: Whether or not the object is hidden.
      type: boolean
      example: false
      readOnly: true
    PaymentAllocation:
      title: Payment Allocation
      type: object
      required:
      - amount
      properties:
        id:
          $ref: '#/components/schemas/Id'
        created:
          $ref: '#/components/schemas/ServerTimestamp'
        modified:
          $ref: '#/components/schemas/ServerTimestamp'
        hidden:
          $ref: '#/components/schemas/IsHidden'
        paymentId:
          $ref: '#/components/schemas/Id'
        orderId:
          $ref: '#/components/schemas/NullableId'
        invoiceItemId:
          allOf:
          - readOnly: true
          - $ref: '#/components/schemas/NullableId'
        jobId:
          $ref: '#/components/schemas/NullableId'
        amount:
          $ref: '#/components/schemas/MoneyAmount'
        refundedAmount:
          allOf:
          - readOnly: true
          - $ref: '#/components/schemas/MoneyAmount'
    Id:
      title: Entity Identifier
      description: A lowercase [ULID](https://github.com/ulid/spec) entity identifier
      type: string
      format: ulid
      example: 01h35ccwymj5ctckp8px1azhg6
      readOnly: true
    ErrorValidation:
      description: A validation error.
      type: object
      properties:
        type:
          description: A namespace URI uniquely identifying the error type.
          type: string
          enum:
          - validation-error
        title:
          description: A short description of the error encountered.
          type: string
          example: Validation Error
        detail:
          description: Breakdown of what fields valid validation and why
          type: object
        status:
          description: The HTTP status code associated with this error.
          type: integer
          example: 400
    List:
      title: Collection
      description: A collection (or list) of resources.
      type: object
      required:
      - type
      - items
      properties:
        meta:
          description: Metadata describing the current result set.
          type: object
          readOnly: true
          properties:
            currentPage:
              description: The current page of results returned.
              type: integer
            totalPages:
              description: 'The total number of pages in the result set. This is affected by

                the `pageSize` parameter (`totalItems / pageSize == totalPages`).'
              type: integer
            totalItems:
              description: 'The total number of items in the result set. This may be

                affected by active search/filter parameters.'
              type: integer
            rows:
              description: The number of rows returned per page for the current result set.
              type: integer
        type:
          $ref: '#/components/schemas/ResourceType'
        items:
          description: A collection of resources returned in the current result set.
          type: array
          items:
            type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Jobs & Contacts
  tags:
  - Jobs
  - Job Contacts
  - Job Worksheets
  - Contacts
  - Events
  - Files
  - Galleries
  - Notes
  - Orders
  - Payment
- name: Studio Settings
  tags:
  - Studio
  - Brands
  - Custom Fields
  - Discounts
  - Discount Types
  - Event Types
  - File Types
  - Job Closed Reasons
  - Job Roles
  - Job Types
  - Lead Sources
  - Lead Statuses
  - Payment Methods
  - Products
  - Product Types
  - Profit Centers
  - Tax Groups
  - Tax Rates
  - Timezones
  - Users
- name: API Resources
  tags:
  - Rest Hooks