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. 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)
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:
    Product:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          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
    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.
    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
    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