compsniper-com Shipping Rates API

openapi: 3.2.0
info:
  title: CompSniper Marketplace and Shipping Shipping Rates API
  version: 2.3.0
  description: Public eBay (including up to 3 years of sold history), Poshmark, Mercari, TCGplayer, Grailed, Depop and PSA graded card (prices by grade, population) data plus a separate quote-only US shipping-rates product. Shipping quotes separate applicable services from carrier-packaging and content-restricted options, use an independent subscription and quota, and do not consume sold-comps requests or purchased credits.
  contact:
    name: CompSniper
    url: https://compsniper.com
servers:
- url: https://api.compsniper.com
security:
- bearerAuth: []
tags:
- name: Shipping Rates
paths:
  /v1/shipping/rates:
    post:
      tags:
      - Shipping Rates
      summary: Get eBay shipping-rate estimates
      description: Returns quote-only shipping estimates for a US origin ZIP, US destination ZIP, package weight, and dimensions. Applicable services are returned in rates. Carrier-packaging and content-restricted services are returned in conditionalRates unless the caller explicitly confirms the requirement. Preserves retail and eBay discounted prices when available. Requires a separate Shipping Rates subscription and consumes one shipping request only when usable applicable rates are returned.
      operationId: getShippingRates
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 128
          pattern: ^[!-~]+$
        description: Replays a completed identical quote without consuming another shipping request. Use a new key for a different request body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingRateRequest'
      responses:
        '200':
          description: Usable shipping-rate estimates. One separate shipping request is consumed unless this is an idempotent replay.
          headers:
            X-Shipping-Plan:
              schema:
                type: string
            X-Shipping-Usage-Limit:
              schema:
                type: integer
            X-Shipping-Usage-Used:
              schema:
                type: integer
            X-Shipping-Usage-Remaining:
              schema:
                type: integer
            X-Shipping-Usage-Reset:
              schema:
                type: string
                format: date-time
            X-Idempotent-Replay:
              schema:
                type: boolean
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingRateResponse'
        '400':
          description: Malformed JSON or invalid route or package details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Credential lacks access or the account has no active Shipping Rates subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '409':
          description: Idempotency key conflict or an identical request with that key is still running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '413':
          description: Request body exceeds 16 KB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: No shipping services were available. No shipping request is consumed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Shipping rate limit or independent monthly shipping quota exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Shipping-rate source is temporarily unavailable. No shipping request is consumed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '503':
          description: Shipping-rate capacity is temporarily busy. No shipping request is consumed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
  /v1/shipping/usage:
    get:
      tags:
      - Shipping Rates
      summary: Get Shipping Rates usage
      description: Returns the authenticated account's separate Shipping Rates plan, quota, usage, rate limit, and billing period.
      operationId: getShippingRateUsage
      responses:
        '200':
          description: Current independent Shipping Rates entitlement and usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingRateUsageResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '403':
          description: Credential lacks access to account usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
components:
  schemas:
    ShippingRateResponse:
      type: object
      required:
      - source
      - rateType
      - currency
      - totalRates
      - totalConditionalRates
      - fetchedAt
      - validUntil
      - requestId
      - rates
      - conditionalRates
      properties:
        source:
          type: string
          enum:
          - ebay_shipping_calculator
        rateType:
          type: string
          enum:
          - estimate
        currency:
          type: string
          example: USD
        totalRates:
          type: integer
          minimum: 1
          description: Services currently applicable to the submitted package and content declarations.
        totalConditionalRates:
          type: integer
          minimum: 0
          description: Additional services requiring specific carrier packaging or eligible contents.
        fetchedAt:
          type: string
          format: date-time
        validUntil:
          type: string
          format: date-time
        requestId:
          type: string
          format: uuid
        rates:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ShippingRate'
        conditionalRates:
          type: array
          items:
            $ref: '#/components/schemas/ShippingRate'
    ApiError:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        retry_after:
          type: integer
          description: Seconds before a temporary rate_limited request may be retried.
        reset_at:
          type: string
          format: date-time
          description: Billing-cycle reset for quota_exceeded.
        plan:
          type: string
        quota:
          type: integer
        used:
          type: integer
        remaining:
          type: integer
        rollover_balance:
          type: integer
          description: Temporary carried-over requests remaining.
        upgrade_url:
          type: string
          format: uri
          description: Plan-management URL for quota_exceeded.
        credit_balance:
          type: integer
          description: Non-expiring purchased credits remaining.
        purchase_credits_url:
          type: string
          format: uri
          description: Credit purchase URL for quota_exceeded.
        subscription_url:
          type: string
          format: uri
          description: Shipping Rates plan URL for shipping_subscription_required or shipping_quota_exceeded.
    ShippingRateUsageResponse:
      type: object
      required:
      - plan
      - status
      - quota
      - used
      - remaining
      - rateLimitPerMinute
      - subscriptionUrl
      properties:
        plan:
          type: string
          example: shipping-10k
        status:
          type: string
          example: active
        quota:
          type: integer
          minimum: 0
        used:
          type: integer
          minimum: 0
        remaining:
          type: integer
          minimum: 0
        rateLimitPerMinute:
          type: integer
          minimum: 0
        periodStart:
          type: string
          format: date-time
        periodEnd:
          type: string
          format: date-time
        subscriptionUrl:
          type: string
          format: uri
    ShippingRateRequest:
      type: object
      additionalProperties: false
      required:
      - shipFrom
      - shipTo
      - package
      properties:
        ebaySite:
          type: string
          enum:
          - ebay.com
          default: ebay.com
        shipFrom:
          type: object
          additionalProperties: false
          required:
          - postalCode
          properties:
            countryCode:
              type: string
              enum:
              - US
              default: US
            postalCode:
              type: string
              pattern: ^[0-9]{5}(-[0-9]{4})?$
              example: '10001'
        shipTo:
          type: object
          additionalProperties: false
          required:
          - postalCode
          properties:
            countryCode:
              type: string
              enum:
              - US
              default: US
            postalCode:
              type: string
              pattern: ^[0-9]{5}(-[0-9]{4})?$
              example: '90210'
        package:
          type: object
          additionalProperties: false
          required:
          - weight
          - dimensions
          properties:
            type:
              type: string
              default: custom
              enum:
              - custom
              - usps_flat_rate_envelope
              - usps_padded_flat_rate_envelope
              - usps_legal_flat_rate_envelope
              - usps_small_flat_rate_box
              - usps_medium_flat_rate_box
              - usps_large_flat_rate_box
              - usps_express_flat_rate_envelope
              - fedex_one_rate_envelope
              - fedex_one_rate_pak
              - fedex_one_rate_extra_small_box
              - fedex_one_rate_small_box
              - fedex_one_rate_medium_box
              - fedex_one_rate_large_box
              - fedex_one_rate_extra_large_box
              - fedex_one_rate_tube
              description: Select custom unless the shipment will use the exact named carrier packaging.
            weight:
              oneOf:
              - type: object
                additionalProperties: false
                required:
                - value
                - unit
                properties:
                  value:
                    type: number
                    maximum: 150
                    example: 2
                    exclusiveMinimum: 0
                  unit:
                    type: string
                    enum:
                    - lb
              - type: object
                additionalProperties: false
                required:
                - value
                - unit
                properties:
                  value:
                    type: number
                    maximum: 2400
                    example: 32
                    exclusiveMinimum: 0
                  unit:
                    type: string
                    enum:
                    - oz
            dimensions:
              type: object
              additionalProperties: false
              required:
              - length
              - width
              - height
              - unit
              properties:
                length:
                  type: number
                  maximum: 120
                  example: 10
                  exclusiveMinimum: 0
                width:
                  type: number
                  maximum: 120
                  example: 8
                  exclusiveMinimum: 0
                height:
                  type: number
                  maximum: 120
                  example: 4
                  exclusiveMinimum: 0
                unit:
                  type: string
                  enum:
                  - in
            irregular:
              type: boolean
              default: false
        contents:
          type: object
          additionalProperties: false
          properties:
            mediaMailEligible:
              type: boolean
              default: false
              description: Set true only when the contents qualify under USPS Media Mail standards.
    ShippingRate:
      type: object
      required:
      - carrierCode
      - serviceName
      - serviceCode
      - serviceGroup
      - tracking
      - estimatedDeliveryMinHours
      - estimatedDeliveryMaxHours
      - includedCoverage
      - fastest
      - discountedPrice
      - retailPrice
      - effectivePrice
      - priceSource
      - savingsPercent
      - eligibility
      properties:
        carrierCode:
          type: string
          example: USPS
        serviceName:
          type: string
          example: USPS Ground Advantage
        serviceCode:
          type: string
          example: USPSParcel
        serviceGroup:
          type:
          - string
          - 'null'
        tracking:
          type: boolean
        estimatedDeliveryMinHours:
          type:
          - integer
          - 'null'
        estimatedDeliveryMaxHours:
          type:
          - integer
          - 'null'
        includedCoverage:
          type:
          - string
          - 'null'
        fastest:
          type: boolean
          description: True when this applicable service has the shortest maximum delivery window. Ties are allowed.
        discountedPrice:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/ShippingPrice'
        retailPrice:
          $ref: '#/components/schemas/ShippingPrice'
        effectivePrice:
          $ref: '#/components/schemas/ShippingPrice'
        priceSource:
          type: string
          enum:
          - ebay_discounted
          - retail
        savingsPercent:
          type:
          - integer
          - 'null'
          minimum: 0
        eligibility:
          type: object
          required:
          - status
          - requirements
          properties:
            status:
              type: string
              enum:
              - eligible
              - conditional
            requirements:
              type: array
              items:
                type: object
                required:
                - type
                - code
                - message
                properties:
                  type:
                    type: string
                    enum:
                    - carrier_packaging
                    - eligible_contents
                  code:
                    type: string
                  message:
                    type: string
    ShippingPrice:
      type: object
      required:
      - min
      - max
      - currency
      properties:
        min:
          type: string
          example: '10.05'
        max:
          type:
          - string
          - 'null'
          example: null
        currency:
          type: string
          example: USD
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send your API key as ''Authorization: Bearer cs_live_...''.'