openapi: 3.1.0
info:
  title: Sendoso Marketplace and SmartSend 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. SmartSend picks the
    gift for you based on the recipient's interests and preferences.


    Sendoso does not publish an OpenAPI document. This description was generated by API
    Evangelist from Sendoso's own published reference pages at https://developer.sendoso.com —
    every path, method, parameter and response field below is traceable to the page named in
    that operation's `externalDocs`.
  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)
externalDocs:
  description: Sendoso Marketplace / SmartSend documentation
  url: https://developer.sendoso.com/marketplace/overview/introduction
security:
  - OAuth2: []
tags:
  - name: Marketplace
    description: The Sendoso marketplace catalog and sending from it.
  - name: SmartSend
    description: AI-selected gift recommendations and sending them.
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'
  /api/v3/smartsend/recommendations:
    get:
      operationId: getGiftRecommendations
      summary: Get Gift Recommendations
      description: Retrieves a list of recommendations for a given recipient email.
      tags: [SmartSend]
      externalDocs:
        url: https://developer.sendoso.com/marketplace/reference/recommendations/get-recommendations
      security:
        - OAuth2: [smartsend]
      parameters:
        - name: recipient_email
          in: query
          required: true
          description: The email of the recipient.
          schema:
            type: string
        - name: price_lte_usd
          in: query
          required: false
          description: The maximum price of products in USD.
          schema:
            type: integer
        - name: ship_to_country_code
          in: query
          required: false
          description: The country code to ship to.
          schema:
            type: string
      responses:
        '200':
          description: Recommended products.
          content:
            application/json:
              schema:
                type: object
                required: [products]
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecommendedProduct'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v3/smartsend/recommendations/send:
    post:
      operationId: sendRecommendation
      summary: Send a Recommendation
      description: Automatically pick and send a recommendation to a recipient.
      tags: [SmartSend]
      externalDocs:
        url: https://developer.sendoso.com/marketplace/reference/recommendations/send
      security:
        - OAuth2: [smartsend]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recipient_email, recipient_first_name, recipient_last_name]
              properties:
                recipient_email:
                  type: string
                recipient_first_name:
                  type: string
                recipient_last_name:
                  type: string
                price_lte_usd:
                  type: integer
                  description: Limit the maximum price of the product in USD.
                ship_to_country_code:
                  type: string
                message:
                  type: string
                gift_exchange_enabled:
                  type: boolean
                meeting_url:
                  type: string
                require_approval:
                  type: boolean
      responses:
        '200':
          description: Send created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketplaceSendResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  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.
  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:
    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
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
    RecommendedProduct:
      type: object
      required: [id, name, description, interests, variants]
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        interests:
          type: array
          description: The interests the product was recommended on.
          items:
            type: string
        variants:
          type: array
          items:
            $ref: '#/components/schemas/Variant'
    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