Developer documentation
Most YourSender users never need to touch the API — connect a store, upload your products, and the system handles deliveries automatically. The API and webhooks are here for sellers who want to integrate YourSender into their own tooling, ERP, or custom storefront.
REST API and webhooks
Base URL
https://api.yoursender.org/api/v1All public endpoints are versioned under /api/v1. Earlier versions are not in service.
Format
All requests and responses are JSON over HTTPS. Every successful response is wrapped in a { data, meta, error } envelope. Error responses use standard HTTP status codes plus an error object with a stable code.
Authentication
Per-tenant API keys with the prefix ys_live_, sent as Authorization: Bearer ys_live_…. Generate and rotate keys in the dashboard. Each key is scoped to one tenant; cross-tenant access is impossible by design.
Rate limits
60 requests per minute per API key, 1,000 per hour soft cap. Webhook ingestion endpoints carry separate, higher limits. Hitting a limit returns 429 with a Retry-After header.
Public API
The public REST API exposes the same resources you see in the dashboard: products, orders, templates, and connections.
/productsList all products for the authenticated tenant. Supports cursor pagination.
/productsCreate a new digital product (FILE, CODE, or HYBRID type). Files are uploaded separately via signed URL.
/products/{id}Fetch a single product, including files and license-code stock.
/products/{id}Update product metadata, template, or platform mappings.
/ordersList all orders. Filter by platform, status, date range, or buyer email.
/orders/{id}Fetch a single order with line items, delivery status, and audit trail.
/orders/{id}/resendRe-deliver an entire order (charges 1 token per item).
/orders/{id}/items/{itemId}/replaceIssue a fresh license code for an item, releasing the previous one (CODE products only).
/templatesList the tenant's email templates.
/connectionsList active platform connections (WooCommerce, eBay, Etsy).
Full request/response schemas live in our OpenAPI spec, exposed at /api/v1/docs on the API host once your account is active.
How platform events reach YourSender
YourSender ingests order events from each connected platform via dedicated webhook endpoints. You don't need to set these up by hand — connecting a store registers them automatically — but understanding the flow helps with troubleshooting.
WooCommerce
POST /webhooks/woocommerce/{tenantId}SignatureX-WC-Webhook-Signature (HMAC-SHA256, base64)The store registers the webhook with a secret YourSender provided at connection time. Every payload is HMAC-validated before it is queued for processing.
eBay
POST /webhooks/ebay/{tenantId}SignatureX-EBAY-SIGNATURE (ECDSA over public-key infrastructure)eBay's Marketplace Notification API delivers events here. The signature is verified against eBay's published public key (cached for 1 hour). A GET on the same path responds to eBay's verification challenge.
Etsy
Polling (no inbound webhook)Signature—Etsy does not offer webhooks for receipts, so YourSender polls /shops/{shop_id}/receipts every five minutes per connected shop. Polling backs off on 429 with Retry-After and stays well under the daily rate budget.
When things go wrong
- Standard HTTP codes. 400 for validation errors, 401/403 for auth, 404 for missing resources, 409 for conflicts (e.g. duplicate SKU), 429 for rate limits, 5xx for server-side problems.
- Stable error codes. Every 4xx response includes an
error.codelikeINSUFFICIENT_TOKENSorCONNECTION_INACTIVEthat you can match on. - Webhook retries. Failed webhook ingestions retry up to 5 times with exponential backoff (1s, 5s, 30s, 5m, 30m). Anything that fails all 5 is moved to a dead-letter queue we monitor.
- Idempotency. Order events are deduplicated for 24 hours; replaying the same payload is safe.
Need detail this page doesn't cover?
Email [email protected] with the question. We answer most developer queries within a business day, and we use the answer to update these docs.