Sendoso Marketplace and SmartSend API

openapi: 3.2.0
info:
  title: Sendoso and SmartSend Marketplace API
  version: '3'
  summary: Browse the Sendoso marketplace catalog, get AI gift recommendations, and send either.
  description: The Sendoso Marketplace and SmartSend API lets you send physical gifts and direct mail from Sendoso's catalog rather than from a pre-configured campaign.
  contact:
    name: Sendoso Developer Support
    email: developers@sendoso.com
    url: https://developer.sendoso.com/
  x-generated-from: documentation
  x-generated-by: API Evangelist enrichment pipeline (local-v1)
  x-generated-on: '2026-08-13'
  x-source-docs: https://developer.sendoso.com/marketplace/overview/introduction
servers:
- url: https://app.sendoso.com
  description: Production
- url: https://app.staging.sendo.so
  description: Sandbox / staging (declared in Sendoso's own reference-page code samples)
security:
- OAuth2: []
tags:
- name: Marketplace
  description: The Sendoso marketplace catalog and sending from it.
paths:
  /api/v3/marketplace/products:
    get:
      operationId: getMarketplaceProducts
      summary: Get Marketplace Products
      description: Retrieves a paginated list of all products in the marketplace catalog.
      tags:
      - Marketplace
      externalDocs:
        url: https://developer.sendoso.com/marketplace/reference/products/get-products
      security:
      - OAuth2:
        - marketplace
      parameters:
      - name: after
        in: query
        required: false
        description: The cursor to start from, returned in the `pagination` object of the previous response.
        schema:
          type: string
      - name: price_gte_usd
        in: query
        required: false
        description: The minimum price of products in USD.
        schema:
          type: integer
      - name: price_lte_usd
        in: query
        required: false
        description: The maximum price of products in USD.
        schema:
          type: integer
      - name: ship_to_country_codes[]
        in: query
        required: false
        description: The country codes to ship to.
        schema:
          type: array
          items:
            type: string
      - name: category_ids[]
        in: query
        required: false
        description: Category IDs to filter products by.
        schema:
          type: array
          items:
            type: string
      - name: text_search
        in: query
        required: false
        description: Filter products by exact text search.
        schema:
          type: string
      responses:
        '200':
          description: A cursor page of catalog products plus the categories in the result set.
          content:
            application/json:
              schema:
                type: object
                required:
                - pagination
                - categories
                - products
                properties:
                  pagination:
                    $ref: '#/components/schemas/CursorPagination'
                  categories:
                    type: array
                    description: Groups of nested categories present in the result set.
                    items:
                      $ref: '#/components/schemas/CategoryGroup'
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v3/marketplace/products/send:
    post:
      operationId: sendMarketplaceProduct
      summary: Send a Product (variant)
      description: Send a product variant to a recipient. Only one product variant can be sent at a time; if more than one is supplied, only the first is processed.
      tags:
      - Marketplace
      externalDocs:
        url: https://developer.sendoso.com/marketplace/reference/products/send
      security:
      - OAuth2:
        - marketplace
      - OAuth2:
        - smartsend
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - variant_ids
              - recipient_email
              - recipient_first_name
              - recipient_last_name
              properties:
                variant_ids:
                  type: array
                  description: Catalog product variant ids fetched from the marketplace.
                  items:
                    type: string
                recipient_email:
                  type: string
                recipient_first_name:
                  type: string
                recipient_last_name:
                  type: string
                sender_first_name:
                  type: string
                sender_last_name:
                  type: string
                sender_email:
                  type: string
                sender_organization_name:
                  type: string
                message:
                  type: string
                  description: An optional message to include with the product.
                gift_exchange_enabled:
                  type: boolean
                  description: Lets recipients exchange the gift for a similar or lower value item in the marketplace.
                meeting_url:
                  type: string
                require_approval:
                  type: boolean
                  description: Places the send on hold for a manager to approve it from the send tracker.
      responses:
        '200':
          description: Send created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceSendResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests. The Marketplace and SmartSend APIs are limited to 100 requests per minute per user and return an `X-Rate-Limit-Reset` header indicating when the limit resets.
      headers:
        X-Rate-Limit-Reset:
          description: The time at which the rate limit will reset.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Variant:
      type: object
      required:
      - id
      properties:
        id:
          type: string
        estimated_total_price:
          type: object
          required:
          - currency
          - price_per_unit
          properties:
            currency:
              type: string
            price_per_unit:
              type: string
        images:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
    MarketplaceSendResult:
      type: object
      required:
      - products
      - send
      properties:
        products:
          type: array
          items:
            type: object
            required:
            - variant_id
            properties:
              variant_id:
                type: string
        send:
          type: object
          required:
          - id
          properties:
            id:
              type: string
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
    Error:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    CursorPagination:
      type: object
      properties:
        after:
          type: string
          description: The cursor to use in the next request to fetch the next page.
        next_page:
          type: object
          properties:
            url:
              type: string
              description: The URL to fetch the next page of products.
    CategoryGroup:
      type: object
      required:
      - group_name
      - children
      properties:
        group_name:
          type: string
        children:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 Authorization Code grant, same authorization server as the Core API. Marketplace operations require the `marketplace` scope; SmartSend operations require `smartsend`.
      flows:
        authorizationCode:
          authorizationUrl: https://app.sendoso.com/oauth/authorize
          tokenUrl: https://app.sendoso.com/oauth/token
          refreshUrl: https://app.sendoso.com/oauth/token
          scopes:
            public: Access the user's basic information.
            write: Send gifts on the user's behalf.
            update: Update the user's account details.
            marketplace: Access the marketplace API.
            smartsend: Access the smartsend API.
externalDocs:
  description: Sendoso Marketplace / SmartSend documentation
  url: https://developer.sendoso.com/marketplace/overview/introduction