Every API here is available over the APIs.io API and to AI agents over MCP.
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