Server-to-server API for Tapebloom's partner pilot. Tapebloom is building its production and fulfillment operations and is opening access to select partners; this contract describes the service being built.
Test mode only. The pilot accepts tb_test_ keys. Live keys are refused with live_mode_unavailable until live payments and production are ready.
Authentication. Send Authorization: Bearer <key>. Keep keys on your server: cross-origin browser requests receive no CORS allowance.
Paths have no trailing slash: /orders/ is a 404, not a redirect. Send paths exactly as listed. A path with repeated slashes, such as /v1//orders, is normalized by the hosting platform with a 308 redirect that carries no Request-Id, before the API sees it.
Errors. Every failure, including 404 and 405, returns { "error": { "code", "message", "field"?, "request_id" } }. Codes are stable strings. Each response carries a Request-Id header.
Amounts are integers in the currency's minor unit, with an explicit lowercase currency.
Idempotency. Writes that change things require an Idempotency-Key header (1–255 printable ASCII characters); quotes accept one. Keys are scoped to your account, mode and operation, and kept for 30 days. Repeating a request with the same key returns the original response (marked Idempotent-Replayed: true); reusing a key for a different request returns 422 idempotency_mismatch. A request that failed is not stored, so you can correct it and retry with the same key. The exception is finalize: its key is bound to the upload and the exact request before any work starts, so retry the same request to resume, and use a new key for a different one. Enabling or disabling a webhook endpoint sets a state, is safe to repeat, and takes no key.
Body size. Request bodies are limited to 2 MiB and answered with 413 body_too_large beyond that. The API stops reading at the limit, but the hosting platform may accept more of the body before the API sees it, so the 413 can arrive after you have sent more than 2 MiB. Upload files go to the signed upload URL, not through the API.
Request limits. An order has at most 100 items and an item at most 200 tracks. These are request limits; each format's manufacturing limits, such as runtime, are checked by validation.
Validation. A new or revised order moves to validating (event order.validating). Every file is fully decoded first, so allow a few minutes for large uploads. Audio must be at least 44.1 kHz and 16-bit, mono or stereo; each item must run no longer than quoted; cassette tracks need a side, and each side must fit the tape. Then the order either moves to awaiting_payment and is charged at once, or to needs_attention with findings to fix by posting a revision. Artwork is checked against each surface's template (see GET /artwork_templates): it must cover the canvas at matching proportions, in RGB, at 300 ppi at its printed size (from 200 ppi staff review it; below, it is refused). Some checks (artwork resolution between 200 and 300 ppi, and artwork on templates not yet approved by a print proof) are reviewed by staff, holding the order in validating without charging it; in test mode these reviews are approved at once. Time in review does not count against your 72-hour price commitment.
Events. GET /events with order_id and after_sequence returns an order's history in sequence with no gaps: use it to reconcile an order or recover missed webhooks. Without order_id, the account-wide list is for browsing; an event committed late can land behind a cursor you have already passed, so do not rely on advancing it to see every event.