Pages · API reference

API reference

Every operation, parameter and schema, from the OpenAPI spec.

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.

Quotes

POST/quotes

Price items and list shipping options

Scope orders:write

A quote expires 24 hours after it is created and can be used by one order (or one revision). Prices come from the price list configured for your mode; a format without a price returns format_unavailable.

Parameters

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)

Body

  • itemsarray of object (1–100 items)required
  • format"vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket"required
  • quantityinteger (1–10000)required
  • runtime_secondsinteger (1–86400)required

    Total programme length of the item.

  • ship_toAddressInputrequired

Responses

  • 201The quote. → Quote
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error

Uploads

POST/uploads

Start an upload

Scope uploads:write

Declares the file and returns a single-use signed URL: PUT the exact bytes to it, then call finalize. A repeat with the same Idempotency-Key returns the same upload with a fresh URL.

Parameters

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Body

  • kind"audio" | "artwork"required
  • size_bytesinteger (≥ 1)required
  • sha256string (pattern ^[0-9a-fA-F]{64}$)required
  • content_typestringrequired

    Example: audio/wav, image/png.

  • filenamestring (1–255 chars)
  • asset_idstring (uuid)

    Add a new version to this existing asset.

  • recording_titlestring (1–300 chars)

Responses

  • 201The upload and where to send the bytes. → UploadCreated
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
GET/uploads/{id}

Get an upload

Scope uploads:write

The upload's state: created (waiting for the bytes), processing (finalize was called and the bytes are being verified), finalized (with the asset_version_id to use in orders) or rejected (with rejected_reason: size_mismatch, checksum_mismatch, file_missing, verification_failed (the file could not be checked after several tries; uploading it again usually works) or upload_expired; start a new upload). An upload that never receives its bytes is rejected as upload_expired after a day. While polling, wait 2 seconds before the first check, then double the wait after each check, up to 30 seconds between checks; stop at finalized or rejected.

Parameters

  • idpath · string (uuid)required

    The upload.

Responses

  • 200The upload. → Upload
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/uploads/{id}/finalize

Verify and finalize an upload

Scope uploads:write

Call once the bytes are PUT. Checks the stored size against the declaration and moves the file out of reach of the upload URL, so it can no longer be replaced. The bytes are then checked against the declared SHA-256 in the background, whatever their size: the response is 202 with state: processing, and GET /uploads/{id} shows the result, usually within a minute (longer for very large files). Poll it with backoff: 2 seconds, doubling to at most 30. A finalized upload has an immutable asset version (asset_version_id). Calling finalize again with the same Idempotency-Key is safe at any time, including after a timeout: it resumes the work and returns the current state, and once the upload is finalized it returns the version marked Idempotent-Replayed: true. The key is bound to this upload and this exact request before any work starts, so the same key with a different request is refused with idempotency_mismatch even if the first one failed. A file that does not match its declaration is rejected (422 size_mismatch or checksum_mismatch, or rejected in GET /uploads/{id}). File-quality checks run as soon as the file is finalized (each file is fully decoded) and are applied at order validation; see Validation.

Parameters

  • idpath · string (uuid)required

    The upload.

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Responses

  • 200The finalized asset version. → UploadFinalized
  • 202The bytes are being verified; see GET /uploads/{id}. → UploadProcessing
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 409The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error

Orders

POST/orders

Create an order from a quote

Scope orders:write

The items must match the quote's formats and quantities, in order, and reference finalized asset versions of your account and mode. rights_warranty: true records that you accept the rights warranty in your partner agreement. The quote's price, address and shipping are committed for 72 hours; validation confirms against that commitment. Your account needs a card on file in this mode first (409 payment_method_required; see POST /billing/setup). In live mode an account owner must also have accepted the partner terms in the partner portal (409 partner_terms_required).

Parameters

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Body

  • quote_idstring (uuid)required
  • shipping_servicestringrequired

    One of the quote's shipping_options.

  • itemsarray of object (1–100 items)required
  • format"vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket"required
  • quantityinteger (1–10000)required
  • surfacesobject

    Artwork per printed surface, e.g. { "front_insert": "<artwork version id>" }. The surfaces of each format are listed by GET /artwork_templates; a surface you leave out prints Tapebloom's default design. Artwork covers the template's whole canvas (trim plus bleed). Replaces the earlier artwork_version_id, which is now refused with field_removed.

  • tracksarray of object (1–200 items)required
  • asset_version_idstring (uuid)required

    A finalized audio asset version.

  • side"A" | "B"

    Cassettes: the side the track plays on. Required for cassettes.

  • titlestring (1–200 chars)

    Printed in tracklists.

  • artiststring (1–200 chars)

    Printed in tracklists.

  • rights_warrantytruerequired
  • titlestring (1–300 chars)
  • external_refstring (1–200 chars)

    Your own reference.

Responses

  • 201The order, in received. → Order
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 409The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
GET/orders

List orders, newest first

Scope orders:read

Parameters

  • statequery · "received" | "validating" | "needs_attention" | "materials_hold" | "awaiting_payment" | "released" | "cancelled" | "complete"

    Only orders in this state.

  • limitquery · integer (1–100)

    Page size. Default 20.

  • starting_afterquery · string (uuid)

    The last order id of the previous page.

Responses

  • 200A page of orders. → list of OrderSummary
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
GET/orders/{id}

Get an order

Scope orders:read

The order with its current items, amounts and latest payment as separate objects.

Parameters

  • idpath · string (uuid)required

    The order.

Responses

  • 200The order. → Order
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/orders/{id}/revisions

Fix an order that needs attention

Scope orders:write

Only from needs_attention. New items replace the current ones (earlier revisions stay as history) and the order returns to validation. Different formats or quantities, a different shipping service, or an expired price commitment need a new quote_id. Every revision replaces the order's content, so each needs rights_warranty: true: an explicit acceptance, recorded with the API key, time and warranty version, for that revision.

Parameters

  • idpath · string (uuid)required

    The order.

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Body

  • itemsarray of object (1–100 items)required
  • format"vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket"required
  • quantityinteger (1–10000)required
  • surfacesobject

    Artwork per printed surface, e.g. { "front_insert": "<artwork version id>" }. The surfaces of each format are listed by GET /artwork_templates; a surface you leave out prints Tapebloom's default design. Artwork covers the template's whole canvas (trim plus bleed). Replaces the earlier artwork_version_id, which is now refused with field_removed.

  • tracksarray of object (1–200 items)required
  • asset_version_idstring (uuid)required

    A finalized audio asset version.

  • side"A" | "B"

    Cassettes: the side the track plays on. Required for cassettes.

  • titlestring (1–200 chars)

    Printed in tracklists.

  • artiststring (1–200 chars)

    Printed in tracklists.

  • reasonstring (1–500 chars)
  • quote_idstring (uuid)
  • shipping_servicestring
  • rights_warrantytruerequired

Responses

  • 201The revised order, back in validating. → Order
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 409The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/orders/{id}/cancel

Cancel an order

Scope orders:write

Before release the order is cancelled, reserved materials are returned and any payment is refunded. After release the order does not change: the response is 409 order_released with the exception_id opened for your request.

Parameters

  • idpath · string (uuid)required

    The order.

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Body

  • reasonstring (pattern ^[a-z][a-z0-9_]{0,63}$)

    Example: changed_mind.

Responses

  • 200The cancelled order. → Order
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 409The order was already released (order_released, with exception_id), or another conflict. → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error

Artwork templates

GET/artwork_templates

Artwork templates

Scope orders:read

The print template of every surface of every format, in the version new orders pin: physical size in millimetres, bleed, safe area, folds, the printable mask, the zone kept for each unit's QR code, and the resolution artwork needs. A template is provisional until a print-and-fit proof approves it; its geometry may then change in a new version, which only later orders pin.

Parameters

  • formatquery · "vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket"

    Only this format's surfaces.

Responses

  • 200The current templates. → list of ArtworkTemplate
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error

Events

GET/events

Event history

Scope events:read

With order_id: that order's events after after_sequence, in sequence, with no gaps. Without: your account's events after starting_after, oldest first, for browsing (see Events above).

Parameters

  • order_idquery · string (uuid)

    One order's events.

  • after_sequencequery · integer (≥ 0)

    With order_id: events after this sequence number.

  • starting_afterquery · string (uuid)

    Without order_id: events after this event.

  • typequery · string (pattern ^[a-z_]+\.[a-z_]+$)

    Only events of this type.

  • limitquery · integer (1–100)

    Page size. Default 50.

Responses

  • 200A page of events. → list of Event
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error

Billing

GET/billing

Card on file

Scope billing:read

The card orders in this mode are charged to, or payment_method: null when none is saved. Each order is charged once, off-session, for its committed total (product plus quoted shipping) when it reaches awaiting_payment. A declined card is not charged again until you save a new one; the order then waits in awaiting_payment and you receive payment.failed.

Responses

  • 200Billing for this key's account and mode. → Billing
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/billing/setup

Save a card

Scope billing:write

Returns a Stripe-hosted page where you save a card for this mode (test mode accepts Stripe's test cards). Card details go to Stripe only; Tapebloom keeps the brand, last four digits and expiry. Completing the page replaces the card on file, and orders waiting after a declined charge are charged again with the new card. The page expires at expires_at.

Body

  • return_urlstring (uri, ≤ 2000 chars)required

    Where Stripe sends you after the card is saved.

  • cancel_urlstring (uri, ≤ 2000 chars)

    Where Stripe sends you if you leave without saving. Defaults to return_url.

Responses

  • 201The setup page. → BillingSetup
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
  • 503Billing is not available in this mode yet (billing_unavailable). → Error

Webhook endpoints

POST/webhook_endpoints

Add a webhook endpoint

Scope webhooks:manage

The response includes the endpoint's signing secret; store it, as it is not shown again except in a replay of this request. A replay returns the endpoint's current settings (for example enabled: false if it was disabled since) with the originally issued secret while that secret still signs, and without secret after it has been rotated out. At most 10 endpoints can be enabled per mode (too_many_endpoints). The URL must be https with a valid port (in test mode also http://localhost or http://127.0.0.1); one that cannot receive deliveries is refused with invalid_url. Omit event_types to receive every type.

Parameters

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Body

  • urlstring (uri, ≤ 2048 chars)required
  • event_typesarray of "order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped" (1–50 items)
  • descriptionstring (1–200 chars)

Responses

  • 201The endpoint and its signing secret. → WebhookEndpointWithSecret
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 409The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
GET/webhook_endpoints

List webhook endpoints, newest first

Scope webhooks:manage

Enabled and disabled endpoints, without secrets.

Parameters

  • limitquery · integer (1–100)

    Page size. Default 20.

  • starting_afterquery · string (uuid)

    The last endpoint id of the previous page.

Responses

  • 200A page of endpoints. → list of WebhookEndpoint
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
GET/webhook_endpoints/{id}

Get a webhook endpoint

Scope webhooks:manage

Without its secret.

Parameters

  • idpath · string (uuid)required

    The endpoint.

Responses

  • 200The endpoint. → WebhookEndpoint
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/webhook_endpoints/{id}/enable

Enable an endpoint

Scope webhooks:manage

Safe to repeat; takes no Idempotency-Key. Fails with too_many_endpoints when 10 are already enabled.

Parameters

  • idpath · string (uuid)required

    The endpoint.

Responses

  • 200The endpoint. → WebhookEndpoint
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 409The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/webhook_endpoints/{id}/disable

Disable an endpoint

Scope webhooks:manage

Safe to repeat; takes no Idempotency-Key. A disabled endpoint receives no new deliveries; pending ones are abandoned once their retry window ends.

Parameters

  • idpath · string (uuid)required

    The endpoint.

Responses

  • 200The endpoint. → WebhookEndpoint
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/webhook_endpoints/{id}/rotate_secret

Issue a new signing secret

Scope webhooks:manage

The old secret keeps signing alongside the new one for overlap_hours (default 24, 0 to 168), so each delivery carries one v1 signature per active secret and you can switch without a gap. The response includes the new secret, shown only here and in a replay of this request. Like create, a replay returns the endpoint's current settings with that secret while it still signs, and without secret once it has been rotated out.

Parameters

  • idpath · string (uuid)required

    The endpoint.

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Body

  • overlap_hoursinteger (0–168)

    Default 24.

Responses

  • 200The endpoint and its new secret. → WebhookEndpointWithSecret
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
GET/webhook_endpoints/{id}/deliveries

An endpoint's deliveries, newest first

Scope webhooks:manage

Parameters

  • idpath · string (uuid)required

    The endpoint.

  • statequery · "pending" | "delivered" | "abandoned"

    Only deliveries in this state.

  • limitquery · integer (1–100)

    Page size. Default 20.

  • starting_afterquery · string (uuid)

    The last delivery id of the previous page.

Responses

  • 200A page of deliveries. → list of WebhookDelivery
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error

Webhook deliveries

GET/webhook_deliveries/{id}

A delivery with every attempt

Scope webhooks:manage

Parameters

  • idpath · string (uuid)required

    The delivery.

Responses

  • 200The delivery, with attempts. → WebhookDelivery
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error
POST/webhook_deliveries/{id}/replay

Send a delivery again

Scope webhooks:manage

The delivery becomes due now with a new 3-day retry window. The event's id, sequence and body are unchanged; each attempt is freshly signed. Retrying with the same Idempotency-Key returns the first response and never schedules another send, even if the delivery has succeeded since; send a new key for an intentional resend. Fails with endpoint_disabled or, while it is being sent, delivery_in_flight.

Parameters

  • idpath · string (uuid)required

    The delivery.

  • Idempotency-Keyheader · string (pattern ^[\x21-\x7e]{1,255}$)required

Responses

  • 200The delivery as requeued, with attempts. → WebhookDelivery
  • 400The body is not JSON, or the Idempotency-Key is missing or malformed. → Error
  • 401The API key is missing or not valid (missing_api_key, invalid_api_key). → Error
  • 403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable). → Error
  • 404No such resource for this key, or no such path. → Error
  • 409The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required). → Error
  • 413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent. → Error
  • 415The body is not application/json. → Error
  • 422The request is invalid; field names the problem, code says what it is. → Error
  • 429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key. → Error
  • 500Our error. Retrying is safe with the same Idempotency-Key. → Error

Schemas

Billing

  • object"billing"required
  • payment_methodnull or objectrequired

BillingSetup

  • object"billing_setup"required
  • urlstring (uri)required
  • expires_atstring (date-time)required

Error

  • errorobjectrequired
  • codestring (pattern ^[a-z][a-z0-9_]*$)required

    A stable code, such as invalid_sha256.

  • messagestringrequired
  • fieldstring
  • request_idstring (pattern ^req_[0-9a-f]{32}$)required
  • exception_idstring (uuid)

    With order_released: the exception opened for the cancel request.

AddressInput

Unknown fields are ignored.

  • namestring (≤ 200 chars)required
  • line1string (≤ 200 chars)required
  • line2string (≤ 200 chars)
  • citystring (≤ 200 chars)required
  • regionstring (≤ 200 chars)
  • postal_codestring (≤ 200 chars)required
  • countrystring (pattern ^[A-Za-z]{2}$)required
  • phonestring (≤ 200 chars)

Address

  • namestringrequired
  • line1stringrequired
  • line2string
  • citystringrequired
  • regionstring
  • postal_codestringrequired
  • countrystring (pattern ^[A-Z]{2}$)required
  • phonestring

ShippingOption

  • servicestringrequired
  • amount_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • min_daysinteger (≥ 0)
  • max_daysinteger (≥ 0)

Quote

  • idstring (uuid)required
  • object"quote"required
  • environment"test" | "live"required
  • currencystring (pattern ^[a-z]{3}$)required

    ISO 4217 code, lowercase.

  • itemsarray of objectrequired
  • positioninteger (≥ 1)required
  • format"vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket"required
  • quantityintegerrequired
  • runtime_secondsintegerrequired
  • unit_price_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • setup_fee_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • amount_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • subtotal_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • shipping_optionsarray of ShippingOption (≥ 1 items)required
  • ship_toAddressrequired
  • expires_atstring (date-time)required
  • created_atstring (date-time)required

UploadCreated

  • idstring (uuid)required
  • object"upload"required
  • kind"audio" | "artwork"required
  • state"created"required
  • uploadobjectrequired
  • method"PUT"required
  • urlstring (uri)required
  • expires_inintegerrequired

    Seconds the URL stays valid.

UploadFinalized

  • idstring (uuid)required
  • object"upload"required
  • state"finalized"required
  • asset_version_idstring (uuid)required

UploadProcessing

  • idstring (uuid)required
  • object"upload"required
  • state"processing"required

Upload

  • idstring (uuid)required
  • object"upload"required
  • kind"audio" | "artwork"required
  • state"created" | "processing" | "finalized" | "rejected"required
  • asset_version_idstring (uuid)

    Once finalized.

  • rejected_reasonstring

    Once rejected: a stable code. Example: checksum_mismatch.

  • created_atstring (date-time)required

Amount

  • currencystring (pattern ^[a-z]{3}$)required

    ISO 4217 code, lowercase.

  • subtotal_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • shipping_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • total_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

Refund

  • idstring (uuid)required
  • state"pending" | "succeeded" | "failed"required
  • amount_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • currencystring (pattern ^[a-z]{3}$)required

    ISO 4217 code, lowercase.

  • reasonstringrequired
  • created_atstring (date-time)required

Payment

  • idstring (uuid)required
  • state"pending" | "requires_action" | "succeeded" | "failed" | "canceled" | "unknown"required
  • amount_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • currencystring (pattern ^[a-z]{3}$)required

    ISO 4217 code, lowercase.

  • amount_received_minorinteger (≥ 0)

    An amount in the currency's minor unit (cents for usd).

  • currency_receivedstring (pattern ^[a-z]{3}$)

    ISO 4217 code, lowercase.

  • failure_codestring
  • refundsarray of Refundrequired
  • created_atstring (date-time)required

Unit

  • idstring (uuid)required
  • object"unit"required
  • item_positioninteger (≥ 1)required
  • serialinteger (≥ 1)required

    The unit's number within its item.

  • state"made" | "passed" | "scrapped" | "packed" | "shipped" | "returned" | "quarantined"required
  • replaces_unit_idstring (uuid)

    Set on a remade unit: the scrapped unit it replaces.

  • created_atstring (date-time)required

Shipment

  • idstring (uuid)required
  • object"shipment"required
  • state"packing" | "label_created" | "handed_to_carrier" | "voided" | "in_transit" | "delivered" | "returned"required
  • carrierstring
  • servicestring
  • tracking_numberstring
  • tracking_urlstring
  • unit_idsarray of string (uuid)required

    The units in the shipment now. Empty once a voided label releases them.

  • created_atstring (date-time)required
  • state_changed_atstring (date-time)required

ArtworkTemplate

  • idstring (uuid)required
  • object"artwork_template"required
  • format"vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket"required
  • surfacestringrequired

    The key to use in an item's surfaces.

  • versioninteger (≥ 1)required
  • labelstringrequired
  • descriptionstringrequired
  • requiredbooleanrequired

    The surface is printed on every unit.

  • default_designstring

    Printed when you send no artwork for the surface. Missing when artwork is needed.

  • status"provisional" | "approved"required

    provisional until a print-and-fit proof approves the geometry.

  • printer"primera_bravo_4202" | "epson_ecotank"required
  • trimobjectrequired
  • width_mmnumberrequired
  • height_mmnumberrequired
  • bleed_mmnumberrequired

    Extend artwork this far past the trim on every side.

  • safe_mmnumberrequired

    Keep text and faces this far inside the trim.

  • canvasobjectrequired

    Trim plus bleed: the area your artwork must cover.

  • width_mmnumberrequired
  • height_mmnumberrequired
  • foldsarray of objectrequired

    Fold lines from the trim's top-left corner; x folds are vertical.

  • axis"x" | "y"required
  • at_mmnumberrequired
  • maskobject

    The printable area when it is not the whole trim, such as a disc's hub and edge. Missing until measured on the production stock.

  • qr_zoneobject

    Where each unit's QR code prints, from the trim's top-left corner. Keep it plain.

  • x_mmnumberrequired
  • y_mmnumberrequired
  • size_mmnumberrequired
  • target_ppiintegerrequired
  • min_ppiintegerrequired
  • target_pixelsobjectrequired

    The smallest artwork that reaches target_ppi over the canvas. Larger files of the same proportions are fine.

  • widthintegerrequired
  • heightintegerrequired
  • approved_atstring (date-time)
  • created_atstring (date-time)required

Finding

  • codestringrequired

    A stable code. Yours to fix: audio_unreadable, audio_empty, audio_truncated, audio_sample_rate_low (below 44.1 kHz), audio_bit_depth_low (below 16-bit), audio_bit_depth_unknown, audio_channels_unsupported (not mono or stereo), runtime_changed (longer than quoted), track_side_missing and side_runtime_exceeded (cassettes), artwork_unreadable, artwork_too_many_pixels, artwork_format_unsupported, artwork_dimensions_mismatch (proportions differ from the canvas by more than a pixel), artwork_color_cmyk (send RGB, ideally sRGB), artwork_resolution_too_low (below the template's min_ppi at its printed size), artwork_surface_missing (a required surface with no default design). Reviewed by staff: artwork_resolution_low (between min_ppi and target_ppi) and artwork_template_unapproved (the template awaits a print proof), which may be approved, and content_mismatch or file_missing, problems with Tapebloom's stored copy that are never waived: staff check them and, if needed, ask you to upload the file again.

  • kind"partner" | "review"required
  • item_positioninteger (≥ 1)
  • track_positioninteger (≥ 1)
  • surfacestring

    The artwork surface (such as front_insert) or cassette side (side_a, side_b) concerned.

  • measuredobjectrequired

    What was measured, e.g. { "sample_rate": 22050 }.

  • expectedobjectrequired

    What is required, e.g. { "min_sample_rate": 44100 }.

  • review_state"pending" | "approved" | "rejected"

    For review findings. In test mode reviews are approved at once.

Order

  • idstring (uuid)required
  • object"order"required
  • environment"test" | "live"required
  • state"received" | "validating" | "needs_attention" | "materials_hold" | "awaiting_payment" | "released" | "cancelled" | "complete"required
  • attention_reasonstring

    Why the order needs attention, as a code: the first of findings you need to fix, or price_commitment_expired.

  • titlestring
  • external_refstring
  • quote_idstring (uuid)
  • revisioninteger (≥ 1)required
  • findingsarray of Finding

    What validation found in the current revision. partner findings are yours to fix with a revision; review findings are checked by Tapebloom staff (the order waits in validating, and is not charged, until they are decided).

  • itemsarray of objectrequired
  • positioninteger (≥ 1)required
  • format"vinyl_12" | "vinyl_7" | "cassette" | "cd_jewel" | "cd_jacket"required
  • quantityintegerrequired
  • artwork_version_idstring (uuid)

    Only on items from before surfaces, for formats without artwork templates.

  • surfacesarray of object
  • surfacestringrequired
  • asset_version_idstring (uuid)

    Your artwork. Missing when the default design prints.

  • default_designstring

    Tapebloom's design printed when no artwork was sent.

  • templateobjectrequired

    The template version pinned when the item was submitted.

  • idstring (uuid)required
  • versioninteger (≥ 1)required
  • status"provisional" | "approved"required
  • tracksarray of objectrequired
  • positioninteger (≥ 1)required
  • side"A" | "B"
  • asset_version_idstring (uuid)required
  • recording_idstring (uuid)required
  • titlestring
  • artiststring
  • ship_toAddress
  • shippingobject
  • servicestringrequired
  • amount_minorinteger (≥ 0)required

    An amount in the currency's minor unit (cents for usd).

  • amountAmount
  • price_commitment_untilstring (date-time)
  • rights_warranty_accepted_atstring (date-time)
  • paymentPayment
  • unitsarray of Unit

    Physical units made for the order, once released.

  • shipmentsarray of Shipment

    The order is complete once the carrier has accepted shipments holding every unit it needs.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required

OrderSummary

  • idstring (uuid)required
  • object"order"required
  • environment"test" | "live"required
  • state"received" | "validating" | "needs_attention" | "materials_hold" | "awaiting_payment" | "released" | "cancelled" | "complete"required
  • attention_reasonstring
  • titlestring
  • external_refstring
  • revisioninteger (≥ 1)required
  • amountAmount
  • created_atstring (date-time)required
  • updated_atstring (date-time)required

WebhookEndpoint

  • idstring (uuid)required
  • object"webhook_endpoint"required
  • environment"test" | "live"required
  • urlstringrequired
  • descriptionstring
  • event_typesarray of "order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped"

    Missing when the endpoint receives every type.

  • enabledbooleanrequired
  • previous_secret_expires_atstring (date-time)

    During a rotation: when the previous secret stops signing.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required

WebhookEndpointWithSecret

  • idstring (uuid)required
  • object"webhook_endpoint"required
  • environment"test" | "live"required
  • urlstringrequired
  • descriptionstring
  • event_typesarray of "order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped"

    Missing when the endpoint receives every type.

  • enabledbooleanrequired
  • previous_secret_expires_atstring (date-time)

    During a rotation: when the previous secret stops signing.

  • created_atstring (date-time)required
  • updated_atstring (date-time)required
  • secretstring (pattern ^whsec_)

    The signing secret. Missing only from a replay made after the secret stopped signing.

WebhookDelivery

  • idstring (uuid)required
  • object"webhook_delivery"required
  • environment"test" | "live"required
  • endpoint_idstring (uuid)required
  • event_idstring (uuid)required
  • event_type"order.awaiting_payment" | "order.cancelled" | "order.complete" | "order.exception_opened" | "order.materials_hold" | "order.needs_attention" | "order.received" | "order.released" | "order.validating" | "payment.canceled" | "payment.failed" | "payment.requires_action" | "payment.succeeded" | "refund.failed" | "refund.succeeded" | "shipment.delivered" | "shipment.returned" | "shipment.shipped"required
  • order_idstring (uuid)required
  • state"pending" | "delivered" | "abandoned"required
  • attempt_countinteger (≥ 0)required
  • next_attempt_atstring (date-time)

    While pending: when the next attempt is due.

  • deadline_atstring (date-time)required

    Retries stop here.

  • last_status_codeinteger
  • last_errorstring
  • delivered_atstring (date-time)
  • replay_countinteger (≥ 0)required
  • created_atstring (date-time)required
  • attemptsarray of object
  • attempt_numberinteger (≥ 1)required
  • signed_atstring (date-time)required
  • status_codeinteger (100–599)
  • error"timeout" | "network_error" | "blocked_address" | "redirect" | "invalid_url" | "invalid_response"
  • duration_msinteger (≥ 0)
  • created_atstring (date-time)required

Event

  • idstring (uuid)required
  • typestring (pattern ^[a-z_]+\.[a-z_]+$)required
  • occurred_atstring (date-time)required
  • environment"test" | "live"required
  • order_idstring (uuid)required
  • sequenceinteger (≥ 1)required
  • dataobjectrequired

    The fields this event type exposes; always includes order_id, object and object_id.