SMKlog Refunds API

Refund status for label payments, the after-sale question a customer asks: whether the payment behind a session was refunded, why and how much. Unused USPS labels are refunded automatically, and a paid label that cannot be issued is bought again or refunded in full.

GitHub OpenAPI

Operations 1

GET /agent/checkout-session/{session_id}/refund Read whether the payment behind a session was refunded #

Documentation

Specifications

SDKs

Schemas & Data

Other Resources

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/smklog-com:smklog-com-refunds-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

smklog-com-refunds-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: SMKlog Quote Refunds API
  version: 1.5.0
  summary: Live parcel rates from a US origin, a checkout handed to a human, and where that checkout stands.
  description: 'Live parcel rates from USPS, UPS, FedEx and DHL Express for a single shipment sent from a US origin: inside the US, or to Canada, the UK, Germany or Australia. Describe the item in plain words and the packed box size and weight are estimated server-side; supply exact dimensions and weight to skip the estimate. No account and no key: only a create-or-update keyed on your own external_id, or a session write that carries an Idempotency-Key, needs a bearer token, from an OAuth client any agent registers itself at /oauth/register. Rate limited per client (about 80 quote requests per hour); quotes cost real money to produce, so cache on your side and do not poll. Buying a label happens on smklog.com — this API prices and hands the payment to a human, it does not sell. It also tracks labels bought on smklog.com, reports whether a label payment was refunded, serves the monthly parcel shipping price index, works out the billable (dimensional) weight of a box, and lists the carriers’ holiday send-by dates and SMKlog’s shipping restrictions.'
  termsOfService: https://smklog.com/terms
  contact:
    name: SMKlog
    email: info@smklog.com
    url: https://smklog.com/developers/
  x-publisher: SMKlog (SMKLOG-2022 LLC)
servers:
- url: https://quote-api.smklog.com
  description: 'Production. There is no sandbox host: quoting is free and read-only, so production is the place to try it.'
security:
- {}
- clientCredentials:
  - quote
tags:
- name: Refunds
  description: 'Refund status for label payments, the after-sale question a customer asks: whether the payment behind a session was refunded, why and how much. Unused USPS labels are refunded automatically, and a paid label that cannot be issued is bought again or refunded in full.'
paths:
  /agent/checkout-session/{session_id}/refund:
    get:
      operationId: getRefundStatus
      tags:
      - Refunds
      x-agentic-access:
        action-class: connected
        consequence: read
        subject: optional
        audience: https://quote-api.smklog.com
        token:
          max-ttl: 3600
        audit: none
      summary: Read whether the payment behind a session was refunded
      description: 'Where the refund of the human''s label payment stands: not_paid (nothing was paid), none (paid, not refunded), requested (a refund is under way), under_review (an unused label from a carrier other than USPS, decided by an operator), declined (the carrier refused the postage refund because the label was scanned), partially_refunded or refunded — with the amount paid, the amount refunded, the reason (unused_label for the automatic refund of a label the carrier never scanned, other for any other refund) and the refund policy in force. Unused USPS labels are refunded automatically; this operation only reads and never starts a refund (the human writes to SMKlog support with the order_id for that). It answers about the same checkout getCheckoutStatus reports. Reads SMKlog order records only, no carrier call; the status bucket (60 calls an hour per client) applies, shared with getCheckoutStatus. The answer never carries names, addresses, emails or card details.'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^as_[A-Za-z0-9-]{8,80}$
        description: The session_id returned by createPaymentSession or upsertPaymentSession.
        example: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
      responses:
        '200':
          description: session_id, order_id, status, reason, amount_paid, amount_refunded, currency, requested_at, policy and next.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundStatus'
              examples:
                refunded:
                  summary: An unused label, refunded automatically
                  value:
                    session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
                    order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                    status: refunded
                    reason: unused_label
                    amount_paid: 38.42
                    amount_refunded: 38.42
                    currency: USD
                    requested_at: '2026-10-16T14:02:11Z'
                    policy: 'An unused USPS label is refunded automatically: 4 days after purchase without a carrier scan SMKlog asks the carrier to refund the postage, and returns the full payment to the card once the carrier confirms it (usually within two weeks). A return label waits 25 days. An unused label from another carrier is reviewed by an operator. A paid label that cannot be issued is bought again or the payment is refunded in full. For anything else, write to info@smklog.com with the order_id.'
                    next: Refunded. The money returns to the card the human paid with, usually within 5 to 10 business days.
                requested:
                  summary: The unused-label refund is waiting on the carrier
                  value:
                    session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
                    order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                    status: requested
                    reason: unused_label
                    amount_paid: 38.42
                    amount_refunded: 0
                    currency: USD
                    requested_at: '2026-10-16T14:02:11Z'
                    policy: 'An unused USPS label is refunded automatically: 4 days after purchase without a carrier scan SMKlog asks the carrier to refund the postage, and returns the full payment to the card once the carrier confirms it (usually within two weeks). A return label waits 25 days. An unused label from another carrier is reviewed by an operator. A paid label that cannot be issued is bought again or the payment is refunded in full. For anything else, write to info@smklog.com with the order_id.'
                    next: A refund is under way; nothing for the agent to do. The money returns to the card the human paid with.
                none:
                  summary: Paid, label in use, nothing refunded
                  value:
                    session_id: as_3f9c1b2e-7d64-4a8e-9c0f-5b2d1e8a7c33
                    order_id: c1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f
                    status: none
                    reason: null
                    amount_paid: 38.42
                    amount_refunded: 0
                    currency: USD
                    requested_at: null
                    policy: 'An unused USPS label is refunded automatically: 4 days after purchase without a carrier scan SMKlog asks the carrier to refund the postage, and returns the full payment to the card once the carrier confirms it (usually within two weeks). A return label waits 25 days. An unused label from another carrier is reviewed by an operator. A paid label that cannot be issued is bought again or the payment is refunded in full. For anything else, write to info@smklog.com with the order_id.'
                    next: Paid and not refunded. The refund policy below says when that changes on its own.
        '404':
          description: session_not_found — unknown, malformed or expired session_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                error: session_not_found
                message: Unknown or expired session_id. Sessions live 30 days from their last create or update.
        '429':
          description: rate_limited — 60 calls an hour per client, shared with getCheckoutStatus. RateLimit-Reset and Retry-After say how many seconds until the hourly window turns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                error: rate_limited
                message: Too many Smart Quote API requests from this client. Try again later.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
components:
  headers:
    Retry-After:
      description: 'Seconds to wait before retrying (RFC 9110 section 10.2.3). On 429: until the hourly window turns, equal to RateLimit-Reset, or until 00:00 UTC for daily_session_limit. On 409 idempotency_key_in_progress: until the first call with the same key has its answer; absent on the other 409 answers.'
      schema:
        type: integer
        minimum: 1
      example: 1740
    RateLimit-Limit:
      description: Requests this client may make in the current one-hour window of the bucket the operation draws on (IETF draft-ietf-httpapi-ratelimit-headers).
      schema:
        type: integer
        minimum: 1
      example: 80
    RateLimit-Remaining:
      description: Requests left in the current window after this one; 0 means the next call answers 429 until RateLimit-Reset elapses.
      schema:
        type: integer
        minimum: 0
      example: 79
    RateLimit-Reset:
      description: Seconds until the window turns and the full allowance returns.
      schema:
        type: integer
        minimum: 1
      example: 1740
    RateLimit-Policy:
      description: 'The policy in force as "<limit>;w=<window seconds>": the allowance and the hour it is measured over.'
      schema:
        type: string
        pattern: ^[0-9]+;w=3600$
      example: 80;w=3600
  schemas:
    RefundStatus:
      type: object
      description: Where the refund of the payment behind a payment session stands, read from SMKlog order records. Never carries names, addresses, emails or card details.
      required:
      - session_id
      - status
      - amount_paid
      - amount_refunded
      - currency
      - policy
      - next
      properties:
        session_id:
          type: string
          description: The session asked about
        order_id:
          type:
          - string
          - 'null'
          description: SMKlog order id of the checkout this answer is about (the one getCheckoutStatus reports), the reference for support; null before the human opened checkout
        status:
          type: string
          enum:
          - not_paid
          - none
          - requested
          - under_review
          - declined
          - partially_refunded
          - refunded
          description: 'not_paid: nothing was paid, nothing to refund. none: paid and not refunded. requested: a refund is under way. under_review: the label looks unused but its carrier is not USPS, so an operator decides. declined: the carrier refused the postage refund because the label was scanned. partially_refunded: part of the payment came back. refunded: the payment was refunded.'
        reason:
          type:
          - string
          - 'null'
          enum:
          - unused_label
          - other
          - null
          description: 'unused_label: the automatic refund of a label the carrier never scanned. other: any other refund SMKlog made (a label that could not be issued after payment, a support decision). null while nothing was refunded or requested.'
        amount_paid:
          type: number
          description: What the human paid, USD; 0 while not_paid
        amount_refunded:
          type: number
          description: What has been refunded so far, USD; 0 until a refund completes
        currency:
          type: string
          enum:
          - USD
          description: ISO currency, USD
        requested_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the automatic unused-label refund was requested from the carrier; null otherwise
        policy:
          type: string
          description: The refund policy in force, in one paragraph built from the settings the refund sweep runs on
        next:
          type: string
          description: What, if anything, the agent should do now
    Problem:
      type: object
      description: 'Every error answer on this host: a stable machine-readable code in error, a sentence for the human in message, and the missing field names when the code is missing_required_fields.'
      required:
      - error
      properties:
        error:
          type: string
          description: 'Stable code: invalid_json, invalid_request, missing_required_fields, product_not_recognized, product_url_not_detected, session_failed, session_in_checkout, session_cancelled, session_not_found, idempotency_key_reused, idempotency_key_in_progress, rate_limited, invalid_token, token_required, tracking_number_required, tracking_not_found, invalid_month, issue_not_found, no_issues'
        message:
          type: string
          description: What went wrong, in a sentence
        missing:
          type: array
          items:
            type: string
          description: Field names still needed, with missing_required_fields and product_not_recognized
        session_id:
          type: string
          description: 'With session_in_checkout, session_cancelled or session_not_found: the session the refusal is about (for session_in_checkout, the one whose checkout the human has started)'
        external_id:
          type: string
          description: 'With session_in_checkout: the external_id you sent'
        available_months:
          type: array
          items:
            type: string
          description: 'With issue_not_found and no_issues: every published price-index month, newest first'
  securitySchemes:
    clientCredentials:
      type: oauth2
      description: 'Optional on every operation but upsertPaymentSession, which always needs one. A token scopes external_id (the create-or-update on createPaymentSession and upsertPaymentSession) and the Idempotency-Key header on the payment-session writes; a call that sends neither works without a token. Any agent registers an OAuth 2.0 client_credentials client itself, with no human step, at POST https://quote-api.smklog.com/oauth/register (RFC 7591; such a client runs at the public limits), or asks info@smklog.com for a client with its own larger hourly bucket (https://smklog.com/auth.md); either way it sends the opaque bearer it gets from /oauth/token. Discovery: /.well-known/oauth-authorization-server (registration_endpoint).'
      flows:
        clientCredentials:
          tokenUrl: https://quote-api.smklog.com/oauth/token
          scopes:
            quote: Price parcels and prepare checkouts from a dedicated per-client rate-limit bucket
externalDocs:
  description: 'Developer portal: docs, schemas, playground, rate limits, status'
  url: https://smklog.com/developers/
x-provenance:
  method: published
  publisher: SMKlog (SMKLOG-2022 LLC)
  source: https://quote-api.smklog.com/openapi.json
  published: '2026-11-07'
x-mcp:
  transport: streamable-http
  endpoint: https://quote-api.smklog.com/mcp
  serverCard: https://quote-api.smklog.com/.well-known/mcp/server-card.json