MarketSDK Listings API

openapi: 3.2.0
info:
  title: Marketsdk Listings API
  version: 1.0.0
  contact: {}
  description: 'Operations tagged Listings across 2 of this provider''s published API definitions: marketsdk-openapi.json, marketsdk-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.marketsdk.com
tags:
- name: Listings
paths:
  /v1/listings:
    post:
      operationId: createListing
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateListingDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Create a listing, as a draft
      tags:
      - Listings
    get:
      description: With a publishable key, only published listings are listed.
      operationId: listListings
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 100
          default: 20
          type: number
      - name: starting_after
        required: false
        in: query
        description: The `next_cursor` of the previous page.
        schema:
          type: string
      - name: seller
        required: false
        in: query
        schema:
          type: string
      - name: category
        required: false
        in: query
        schema:
          type: string
      - name: status
        required: false
        in: query
        schema:
          type: string
          enum:
          - draft
          - published
          - sold
          - expired
          - removed
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: List listings, newest first
      tags:
      - Listings
      x-publishable: true
    servers:
    - url: https://api.marketsdk.com
  /v1/listings/bulk:
    post:
      operationId: createListings
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCreateListingsDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkListingsObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Create up to 100 listings at once, all or none
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
  /v1/listings/{id}:
    get:
      description: With a publishable key, only a published listing can be retrieved.
      operationId: getListing
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Retrieve a listing
      tags:
      - Listings
      x-publishable: true
    patch:
      operationId: updateListing
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateListingDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Update a listing
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
  /v1/listings/{id}/publish:
    post:
      description: Needs an active seller, verified when seller verification is on, and a category that is not prohibited.
      operationId: publishListing
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Not allowed with this key, or the marketplace is read-only.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Publish a listing
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
  /v1/listings/{id}/unpublish:
    post:
      operationId: unpublishListing
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Return a published listing to draft
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
  /v1/listings/{id}/remove:
    post:
      operationId: removeListing
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RemoveListingDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Take a listing down, with a reason
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
  /v1/listings/{id}/media:
    post:
      description: Returns a signed URL, valid for 10 minutes. PUT the file there, then complete the upload. The file is stored under a path that begins with the marketplace id.
      operationId: createMedia
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMediaDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaUploadObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Start a media upload
      tags:
      - Listings
    get:
      operationId: listMedia
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaList'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: A listing's media, pending uploads included
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
  /v1/media/{id}/complete:
    post:
      description: Checks the stored file against the declared type and size.
      operationId: completeMedia
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: The object is not in a state that allows this.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Complete a media upload
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
  /v1/media/{id}:
    delete:
      operationId: deleteMedia
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaObject'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: No API key, or not a valid one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No object with that id in this marketplace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. See `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
      - bearer: []
      summary: Delete media and its file
      tags:
      - Listings
    servers:
    - url: https://api.marketsdk.com
components:
  schemas:
    MoneyObject:
      type: object
      properties:
        amount:
          type: number
          description: Integer minor units.
          example: 4900
        currency:
          type: string
          example: USD
      required:
      - amount
      - currency
    BulkListingsObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/ListingObject'
      required:
      - object
      - data
    ErrorEnvelope:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
      - error
    ListingObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - listing
        id:
          type: string
          example: lst_034XtPDs7UJ0TXzTsdaHZa
        seller:
          type: string
        category:
          type:
          - string
          - 'null'
        title:
          type: string
        description:
          type:
          - string
          - 'null'
        price:
          $ref: '#/components/schemas/MoneyObject'
        quantity:
          type: number
        quantity_available:
          type: number
          description: Not reserved by an open order.
        status:
          type: string
          enum:
          - draft
          - published
          - sold
          - expired
          - removed
        attributes:
          type: object
          additionalProperties: true
        media:
          type: array
          items:
            $ref: '#/components/schemas/MediaObject'
        metadata:
          type: object
          additionalProperties:
            type: string
        published_at:
          type:
          - string
          - 'null'
          format: date-time
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
        removed_reason:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - seller
      - category
      - title
      - description
      - price
      - quantity
      - quantity_available
      - status
      - attributes
      - media
      - metadata
      - published_at
      - expires_at
      - removed_reason
      - created_at
      - updated_at
    MediaList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/MediaObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    MoneyDto:
      type: object
      properties:
        amount:
          type: number
          description: Integer minor units, such as cents.
          example: 4900
        currency:
          type: string
          description: ISO 4217 code. Must be the marketplace currency.
          example: USD
      required:
      - amount
      - currency
    MediaUploadObject:
      type: object
      properties:
        media:
          $ref: '#/components/schemas/MediaObject'
        upload_url:
          type: string
          description: PUT the file here, with the same Content-Type, within 10 minutes. Then complete the upload.
        upload_expires_at:
          type: string
          format: date-time
      required:
      - media
      - upload_url
      - upload_expires_at
    RemoveListingDto:
      type: object
      properties:
        reason:
          type: string
          maxLength: 500
          description: Recorded with the removal.
      required:
      - reason
    MediaObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - media
        id:
          type: string
          example: med_034XtPDs7UJ0TXzTsdaHZa
        listing:
          type: string
        status:
          type: string
          enum:
          - pending
          - ready
        content_type:
          type: string
          example: image/jpeg
        size_bytes:
          type: number
        position:
          type: number
        url:
          type:
          - string
          - 'null'
          description: A signed link to the file, valid for an hour. Null until the upload completes.
        url_expires_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - listing
      - status
      - content_type
      - size_bytes
      - position
      - url
      - url_expires_at
      - created_at
    ListingList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/ListingObject'
        has_more:
          type: boolean
          description: Whether another page follows.
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as `starting_after` (or `cursor` for search) to get the next page.
      required:
      - object
      - data
      - has_more
      - next_cursor
    BulkCreateListingsDto:
      type: object
      properties:
        listings:
          minItems: 1
          maxItems: 100
          description: All are created, or none.
          type: array
          items:
            $ref: '#/components/schemas/CreateListingDto'
      required:
      - listings
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable. Never changes once published.
          example: resource_missing
        message:
          type: string
          description: For people.
          example: No seller has that id.
        param:
          type: string
          description: The request field at fault.
          example: seller
        request_id:
          type: string
          example: req_7Gq0mR2s9xVbN4kT1pLc
      required:
      - code
      - message
      - request_id
    UpdateListingDto:
      type: object
      properties:
        category:
          type:
          - string
          - 'null'
        title:
          type: string
          maxLength: 200
        description:
          type:
          - string
          - 'null'
        price:
          $ref: '#/components/schemas/MoneyDto'
        quantity:
          type: number
          minimum: 1
          description: The total. Cannot go below what open orders have reserved.
        attributes:
          type: object
          additionalProperties: true
        metadata:
          type: object
          additionalProperties:
            type: string
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
    CreateListingDto:
      type: object
      properties:
        seller:
          type: string
          example: sel_034XtPDs7UJ0TXzTsdaHZa
        category:
          type:
          - string
          - 'null'
          example: cat_034XtPDs7UJ0TXzTsdaHZa
        title:
          type: string
          maxLength: 200
        description:
          type:
          - string
          - 'null'
          maxLength: 20000
        price:
          $ref: '#/components/schemas/MoneyDto'
        quantity:
          type: number
          default: 1
          minimum: 1
          maximum: 100000
        attributes:
          type: object
          description: Validated against the category's attribute schema.
          additionalProperties: true
        metadata:
          type: object
          additionalProperties:
            type: string
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When a published listing expires.
      required:
      - seller
      - title
      - price
    CreateMediaDto:
      type: object
      properties:
        content_type:
          type: string
          enum:
          - image/jpeg
          - image/png
          - image/webp
          - image/gif
          - image/avif
        size_bytes:
          type: number
          minimum: 1
          maximum: 10485760
          description: The exact size of the file, in bytes. At most 10 MB.
        position:
          type: number
          default: 0
      required:
      - content_type
      - size_bytes
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: 'An API key: msk_test_sk_…, msk_live_sk_…, or a publishable msk_…_pk_… key where allowed.'
x-refined-from:
- marketsdk-openapi.json
- marketsdk-openapi.json
x-stripe-permissions:
- permission: accounts
  category: Core
  resource: Accounts
  level: Write
  used_for: Create sellers' connected accounts and read their status
- permission: account_links
  category: Connect
  resource: Account Links
  level: Write
  used_for: Onboarding links for sellers
- permission: transfers
  category: Connect
  resource: Transfers
  level: Write
  used_for: Release funds to a seller, and reverse them on a refund
- permission: payment_intents
  category: Core
  resource: Payment Intents
  level: Write
  used_for: Buyer payments, and cancelling unpaid ones
- permission: charges_and_refunds
  category: Core
  resource: Charges and Refunds
  level: Write
  used_for: Refunds, full and partial
- permission: checkout_sessions
  category: Checkout
  resource: Checkout Sessions
  level: Write
  used_for: Hosted checkout, and expiring unpaid sessions
- permission: identity_verification_sessions
  category: Identity
  resource: Verification Sessions and Reports
  level: Write
  used_for: Seller identity verification
- permission: disputes
  category: Core
  resource: Disputes
  level: Read
  used_for: Reading card disputes, to link them to orders
- permission: webhook_endpoints
  category: Webhook Endpoints
  resource: Webhook Endpoints
  level: Write
  used_for: Registering our endpoint on your account