Developer API

Build on the Soto & Segovia Gifting Platform

A RESTful API for ordering, tracking, and managing curated Spanish gourmet gifts at any scale. Integrate gifting into your CRM, sales tools, or AI agents.

Request API KeyBrowse Endpoints

REST

Architecture

JSON

Format

TLS 1.3

Transport

v1

Current Version

Authentication

API Keys

All requests require a Bearer token in the Authorization header. API keys are scoped to your client portal account and can be generated from Settings › API Keys.

Keep your key secret. Rotate it immediately if it is ever exposed. Keys do not expire but can be revoked from your portal at any time.

Sandbox vs Production

Keys prefixed with sk_test_ hit the sandbox environment. Production keys use sk_live_. No real orders are placed in sandbox.

bash
# Include in every request
curl https://api.sotosegoviaimports.com/v1/orders \
  -H "Authorization: Bearer sk_live_••••••••••••••••" \
  -H "Content-Type: application/json"

Base URL

Endpoint Root

All API endpoints are rooted at the base URL below. The current stable version is v1. Version is part of the path, not a header.

Sandbox requests use the same base URL. The environment is determined by your API key prefix.

text
Production:
https://api.sotosegoviaimports.com/v1

Sandbox:
https://api.sotosegoviaimports.com/v1
(use sk_test_ key)

Endpoints

Full Endpoint Reference

Orders

POST/v1/orders
GET/v1/orders
GET/v1/orders/{id}
PATCH/v1/orders/{id}
DELETE/v1/orders/{id}

Products

GET/v1/products
GET/v1/products/{slug}

Recipients

POST/v1/recipients
GET/v1/recipients
GET/v1/recipients/{id}
PATCH/v1/recipients/{id}
DELETE/v1/recipients/{id}

Gift Sends

POST/v1/gifts/send
POST/v1/gifts/bulk
POST/v1/gifts/recommend

Tracking

GET/v1/tracking/{order_id}

Webhooks

POST/v1/webhooks
GET/v1/webhooks
DELETE/v1/webhooks/{id}

Orders

Create & Manage Orders

Create an Order

Places a new gift order. Returns the order object with status pending until payment is confirmed.

Request
POST /v1/orders
Authorization: Bearer sk_live_••••

{
  "product_slug": "iberian-olive-oil-collection",
  "quantity": 1,
  "recipient": {
    "name": "Sarah Johnson",
    "email": "sarah@acme.com",
    "address": {
      "line1": "123 Park Ave",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    }
  },
  "gift_message": "Congratulations on the promotion!",
  "notify_recipient": true
}
Response
{
  "id": "ord_1a2b3c4d",
  "status": "pending",
  "product_slug": "iberian-olive-oil-collection",
  "quantity": 1,
  "amount": 8500,
  "currency": "usd",
  "recipient": {
    "name": "Sarah Johnson",
    "email": "sarah@acme.com"
  },
  "tracking_number": null,
  "created_at": "2026-08-19T21:00:00Z",
  "updated_at": "2026-08-19T21:00:00Z"
}

List Orders

Returns a paginated list of orders. Supports filtering by status, date range, and recipient email.

Request
GET /v1/orders?status=shipped&limit=20&page=1
Authorization: Bearer sk_live_••••
Response
{
  "data": [
    {
      "id": "ord_1a2b3c4d",
      "status": "shipped",
      "recipient": {
        "name": "Sarah Johnson"
      },
      "amount": 8500,
      "created_at": "2026-08-19T21:00:00Z"
    }
  ],
  "meta": {
    "total": 84,
    "page": 1,
    "limit": 20,
    "has_more": true
  }
}

Update an Order

Update address, gift message, or recipient details. Only possible while status is pending.

Request
PATCH /v1/orders/ord_1a2b3c4d
Authorization: Bearer sk_live_••••

{
  "gift_message": "Updated: Congrats on the new role!",
  "recipient": {
    "address": {
      "line1": "456 5th Ave",
      "city": "New York",
      "state": "NY",
      "postal_code": "10018",
      "country": "US"
    }
  }
}
Response
{
  "id": "ord_1a2b3c4d",
  "status": "pending",
  "gift_message": "Updated: Congrats on the new role!",
  "updated_at": "2026-08-19T21:05:00Z"
}

Gift Sends

Bulk Gifting

Send the same gift to multiple recipients in a single API call. Each recipient gets an independent order record. Useful for ABM campaigns and event follow-up sends.

Request
POST /v1/gifts/bulk
Authorization: Bearer sk_live_••••

{
  "product_slug": "spanish-salt-gift-box",
  "gift_message": "Thank you for meeting with us.",
  "recipients": [
    {
      "name": "Marcus Lee",
      "email": "marcus@company.com",
      "address": { "line1": "...", "city": "Austin", "state": "TX", "postal_code": "73301", "country": "US" }
    },
    {
      "name": "Priya Patel",
      "email": "priya@startup.io",
      "address": { "line1": "...", "city": "SF", "state": "CA", "postal_code": "94105", "country": "US" }
    }
  ]
}
Response
{
  "batch_id": "bat_x9y8z7",
  "status": "processing",
  "total": 2,
  "orders": [
    { "id": "ord_aaa111", "recipient_email": "marcus@company.com", "status": "pending" },
    { "id": "ord_bbb222", "recipient_email": "priya@startup.io", "status": "pending" }
  ],
  "created_at": "2026-08-19T21:00:00Z"
}

AI Recommendations

Gift Recommendations

Pass context about a recipient and receive a ranked list of product recommendations with reasoning. Powers the Claude MCP get_gift_recommendation tool.

Request
POST /v1/gifts/recommend
Authorization: Bearer sk_live_••••

{
  "recipient_context": {
    "role": "CFO",
    "industry": "Technology",
    "location": "New York, NY",
    "occasion": "Deal close",
    "budget_cents": 15000
  }
}
Response
{
  "recommendations": [
    {
      "rank": 1,
      "product_slug": "iberian-olive-oil-collection",
      "name": "Iberian Olive Oil Collection",
      "price_cents": 8500,
      "reasoning": "Premium presentation suited to executive gifting. Ships well to NY."
    },
    {
      "rank": 2,
      "product_slug": "premium-salt-vinegar-set",
      "name": "Premium Salt & Vinegar Set",
      "price_cents": 7200,
      "reasoning": "Culinary focus appeals broadly to executives."
    }
  ]
}

Tracking

Shipment Tracking

Poll the tracking endpoint after an order moves to shipped status, or listen for order.shipped and order.delivered webhook events.

Request
GET /v1/tracking/ord_1a2b3c4d
Authorization: Bearer sk_live_••••
Response
{
  "order_id": "ord_1a2b3c4d",
  "carrier": "UPS",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://ups.com/track?num=...",
  "status": "in_transit",
  "estimated_delivery": "2026-08-22",
  "events": [
    {
      "timestamp": "2026-08-20T08:00:00Z",
      "description": "Package picked up",
      "location": "Miami, FL"
    },
    {
      "timestamp": "2026-08-20T18:30:00Z",
      "description": "In transit",
      "location": "Charlotte, NC"
    }
  ]
}

Webhooks

Event Webhooks

Register an HTTPS endpoint to receive real-time event notifications. Each delivery includes an X-SS-Signature header you should verify using your webhook secret.

Available Events

order.created

A new order was successfully placed.

order.shipped

An order has been picked up by the carrier.

order.delivered

Carrier confirmed delivery to the recipient.

order.cancelled

An order was cancelled before fulfillment.

gift.opened

Recipient scanned the gift QR code (if enabled).

Webhook Payload
{
  "id": "evt_abc123",
  "type": "order.shipped",
  "created_at": "2026-08-20T08:00:00Z",
  "data": {
    "order_id": "ord_1a2b3c4d",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "UPS",
    "recipient_email": "sarah@acme.com"
  }
}

# Verify signature
X-SS-Signature: sha256=a1b2c3d4...

Rate Limits

Rate Limits & Pagination

Rate Limits

Standard120 requests / minute
Bulk endpoints20 requests / minute
Recommendations30 requests / minute

Rate limit status is returned in every response via X-RateLimit-Remaining and X-RateLimit-Reset headers. Use exponential backoff on 429 responses.

Pagination

List endpoints use offset pagination via page and limit query parameters. Default limit is 20, max is 100.

Query Params
GET /v1/orders?page=2&limit=50

# Response includes:
{
  "meta": {
    "total": 240,
    "page": 2,
    "limit": 50,
    "has_more": true
  }
}

Errors

Error Codes

All errors return a JSON body with error (machine-readable code) and message (human-readable). HTTP status codes follow standard conventions.

400bad_requestMissing or invalid request parameters.
401unauthorizedInvalid or missing API key.
403forbiddenValid key but insufficient permissions.
404not_foundThe requested resource does not exist.
409conflictDuplicate order or recipient detected.
422unprocessableRequest body is valid JSON but fails validation.
429rate_limit_exceededToo many requests. Back off and retry.
500server_errorInternal error on our side. Retry with exponential backoff.
Error Response
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit of 120 requests per minute.",
  "retry_after": 38
}

SDKs & Tools

Libraries & Integrations

Node.js / TypeScript

Coming Soon
npm install @soto-segovia/api

Python

Coming Soon
pip install soto-segovia

Claude MCP Server

Available
JSON config, no code required

Until native SDKs ship, any HTTP client works. The API is fully OpenAPI 3.1 compliant — import the spec into Postman, Insomnia, or any compatible tool. Request API access to receive the OpenAPI spec.

Get Access

Request Your API Key

We issue API keys manually to ensure quality integrations. Tell us what you are building and we will send sandbox credentials within 24 hours.