MarketSDK Sellers API

openapi: 3.2.0
info:
  title: Marketsdk Sellers API
  version: 1.0.0
  contact: {}
  description: 'Operations tagged Sellers 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: Sellers
paths:
  /v1/sellers:
    post:
      operationId: createSeller
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePartyDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerObject'
        '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'
        '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 seller
      tags:
      - Sellers
    get:
      operationId: listSellers
      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: external_id
        required: false
        in: query
        description: Find the seller with this external id.
        schema:
          type: string
      - name: status
        required: false
        in: query
        schema:
          type: string
          enum:
          - active
          - suspended
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerList'
        '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 sellers, newest first
      tags:
      - Sellers
    servers:
    - url: https://api.marketsdk.com
  /v1/sellers/{id}:
    get:
      operationId: getSeller
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerObject'
        '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 seller
      tags:
      - Sellers
    patch:
      operationId: updateSeller
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePartyDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerObject'
        '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 seller
      tags:
      - Sellers
    delete:
      description: Removes the name, external id, metadata, storefront, and review text, and takes the listings down. Orders and reputation stay, without personal data.
      operationId: eraseSeller
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerObject'
        '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: Erase a seller's personal data
      tags:
      - Sellers
    servers:
    - url: https://api.marketsdk.com
  /v1/sellers/{id}/storefront:
    put:
      operationId: putStorefront
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorefrontDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontObject'
        '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 or replace a seller's storefront
      tags:
      - Sellers
    servers:
    - url: https://api.marketsdk.com
  /v1/sellers/{id}/onboarding_links:
    post:
      description: 'The first link creates the seller''s connected account on your Stripe account: Express, with Stripe collecting what the law requires, your platform paying Stripe''s fees and bearing losses, and only transfers requested. Send the seller to the link; their payouts status follows as Stripe reports it.'
      operationId: createOnboardingLink
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingLinkDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingLinkObject'
        '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: Create a Stripe onboarding link for a seller
      tags:
      - Sellers
    servers:
    - url: https://api.marketsdk.com
  /v1/sellers/{id}/profile:
    get:
      description: Callable with a publishable key. Shows only what a buyer may see.
      operationId: getSellerProfile
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerProfileObject'
        '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 seller's public profile
      tags:
      - Sellers
      x-publishable: true
    servers:
    - url: https://api.marketsdk.com
components:
  schemas:
    StorefrontDto:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        slug:
          type: string
          description: Lowercase letters, digits, and hyphens. Unique per marketplace.
          example: jane-templates
        description:
          type:
          - string
          - 'null'
          maxLength: 5000
        metadata:
          type: object
          additionalProperties:
            type: string
      required:
      - name
      - slug
    SellerProfileObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - seller_profile
        id:
          type: string
        display_name:
          type:
          - string
          - 'null'
        verification_status:
          type: string
          enum:
          - unverified
          - pending
          - verified
          - requires_input
          - canceled
        storefront:
          anyOf:
          - $ref: '#/components/schemas/StorefrontObject'
          - type: 'null'
        reputation:
          $ref: '#/components/schemas/ReputationObject'
      required:
      - object
      - id
      - display_name
      - verification_status
      - storefront
      - reputation
    CreatePartyDto:
      type: object
      properties:
        external_id:
          type: string
          description: Your own id for this person. Unique per marketplace.
          maxLength: 200
        display_name:
          type: string
          maxLength: 200
        metadata:
          type: object
          additionalProperties:
            type: string
      required:
      - external_id
    SellerList:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/SellerObject'
        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
    ErrorEnvelope:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      required:
      - error
    SellerPayoutsObject:
      type: object
      properties:
        status:
          type: string
          enum:
          - not_started
          - pending
          - enabled
          - restricted
          description: '`not_started` before the first onboarding link; `pending` while Stripe onboarding is unfinished or under review; `enabled` when the seller can receive transfers; `restricted` when Stripe needs more from the seller.'
        requirements_due:
          description: What Stripe still needs from the seller, by Stripe's field names. Send a new onboarding link to collect it.
          type: array
          items:
            type: string
        stripe_account:
          type:
          - string
          - 'null'
          description: The seller's connected account on your Stripe account.
      required:
      - status
      - requirements_due
      - stripe_account
    StorefrontObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - storefront
        name:
          type: string
        slug:
          type: string
        description:
          type:
          - string
          - 'null'
        metadata:
          type: object
          additionalProperties:
            type: string
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - name
      - slug
      - description
      - metadata
      - updated_at
    OnboardingLinkDto:
      type: object
      properties:
        return_url:
          type: string
          description: Where Stripe sends the seller when they finish or leave onboarding.
        refresh_url:
          type: string
          description: Where Stripe sends the seller if the link expired. Create a new link there.
        country:
          type: string
          description: The seller's country, two letters. Used only when the seller's Stripe account is created, on the first link. Defaults to your Stripe account's country.
          example: US
      required:
      - return_url
      - refresh_url
    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
    UpdatePartyDto:
      type: object
      properties:
        display_name:
          type:
          - string
          - 'null'
          maxLength: 200
        metadata:
          type: object
          additionalProperties:
            type: string
    OnboardingLinkObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - onboarding_link
        seller:
          type: string
        url:
          type: string
          description: Stripe-hosted onboarding, carrying your branding. Single use, and short-lived.
        expires_at:
          type: string
          format: date-time
        payouts:
          $ref: '#/components/schemas/SellerPayoutsObject'
      required:
      - object
      - seller
      - url
      - expires_at
      - payouts
    SellerVerificationSummary:
      type: object
      properties:
        status:
          type: string
          enum:
          - unverified
          - pending
          - verified
          - requires_input
          - canceled
          description: From the latest identity verification. Once verified, a seller stays verified.
        verified_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - status
      - verified_at
    ReputationObject:
      type: object
      properties:
        completed_orders:
          type: number
          description: order_completed events in the rolling window.
        backed_out:
          type: number
          description: backed_out events in the rolling window.
        disputes_lost:
          type: number
          description: dispute_lost events in the rolling window.
        review_count:
          type: number
          description: Visible reviews in the rolling window.
        average_rating:
          type:
          - number
          - 'null'
          description: Plain mean of those ratings, or null.
        score:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 100
          description: Null until the minimum number of events.
        level:
          type: string
          enum:
          - new
          - low
          - fair
          - good
          - excellent
      required:
      - completed_orders
      - backed_out
      - disputes_lost
      - review_count
      - average_rating
      - score
      - level
    SellerObject:
      type: object
      properties:
        object:
          type: string
          enum:
          - seller
        id:
          type: string
          example: sel_034XtPDs7UJ0TXzTsdaHZa
        external_id:
          type: string
        display_name:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - active
          - suspended
        suspended_reason:
          type:
          - string
          - 'null'
        verification:
          $ref: '#/components/schemas/SellerVerificationSummary'
        payouts:
          $ref: '#/components/schemas/SellerPayoutsObject'
        storefront:
          anyOf:
          - $ref: '#/components/schemas/StorefrontObject'
          - type: 'null'
        reputation:
          $ref: '#/components/schemas/ReputationObject'
        metadata:
          type: object
          additionalProperties:
            type: string
        erased:
          type: boolean
          description: True once the seller's personal data has been erased at your request.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - object
      - id
      - external_id
      - display_name
      - status
      - suspended_reason
      - verification
      - payouts
      - storefront
      - reputation
      - metadata
      - erased
      - created_at
      - updated_at
  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