{
  "openapi": "3.1.0",
  "info": {
    "title": "Tapebloom Partner API",
    "version": "1.0.0-pilot",
    "description": "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.\n\n**Test mode only.** The pilot accepts `tb_test_` keys. Live keys are refused with `live_mode_unavailable` until live payments and production are ready.\n\n**Authentication.** Send `Authorization: Bearer <key>`. Keep keys on your server: cross-origin browser requests receive no CORS allowance.\n\n**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.\n\n**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.\n\n**Amounts** are integers in the currency's minor unit, with an explicit lowercase currency.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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."
  },
  "servers": [
    {
      "url": "https://api.tapebloom.com/v1"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/quotes": {
      "post": {
        "operationId": "createQuote",
        "summary": "Price items and list shipping options",
        "description": "Needs `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": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyOptional"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "format": {
                          "enum": [
                            "vinyl_12",
                            "vinyl_7",
                            "cassette",
                            "cd_jewel",
                            "cd_jacket"
                          ]
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 10000
                        },
                        "runtime_seconds": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 86400,
                          "description": "Total programme length of the item."
                        }
                      },
                      "required": [
                        "format",
                        "quantity",
                        "runtime_seconds"
                      ]
                    }
                  },
                  "ship_to": {
                    "$ref": "#/components/schemas/AddressInput"
                  }
                },
                "required": [
                  "items",
                  "ship_to"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The quote.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Quote"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/uploads": {
      "post": {
        "operationId": "createUpload",
        "summary": "Start an upload",
        "description": "Needs `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": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "kind": {
                    "enum": [
                      "audio",
                      "artwork"
                    ]
                  },
                  "size_bytes": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "sha256": {
                    "type": "string",
                    "pattern": "^[0-9a-fA-F]{64}$"
                  },
                  "content_type": {
                    "type": "string",
                    "examples": [
                      "audio/wav",
                      "image/png"
                    ]
                  },
                  "filename": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255,
                    "pattern": "\\S"
                  },
                  "asset_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Add a new version to this existing asset."
                  },
                  "recording_title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 300,
                    "pattern": "\\S"
                  }
                },
                "required": [
                  "kind",
                  "size_bytes",
                  "sha256",
                  "content_type"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The upload and where to send the bytes.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/uploads/{id}": {
      "get": {
        "operationId": "getUpload",
        "summary": "Get an upload",
        "description": "Needs `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": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The upload.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The upload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Upload"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/uploads/{id}/finalize": {
      "post": {
        "operationId": "finalizeUpload",
        "summary": "Verify and finalize an upload",
        "description": "Needs `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": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The upload.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The finalized asset version.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadFinalized"
                }
              }
            }
          },
          "202": {
            "description": "The bytes are being verified; see `GET /uploads/{id}`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadProcessing"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/orders": {
      "post": {
        "operationId": "createOrder",
        "summary": "Create an order from a quote",
        "description": "Needs `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": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "quote_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "shipping_service": {
                    "type": "string",
                    "description": "One of the quote's shipping_options."
                  },
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "format": {
                          "enum": [
                            "vinyl_12",
                            "vinyl_7",
                            "cassette",
                            "cd_jewel",
                            "cd_jacket"
                          ]
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 10000
                        },
                        "surfaces": {
                          "type": "object",
                          "maxProperties": 10,
                          "propertyNames": {
                            "pattern": "^[a-z][a-z0-9_]{1,39}$"
                          },
                          "additionalProperties": {
                            "type": "string",
                            "format": "uuid",
                            "description": "A finalized artwork asset version."
                          },
                          "description": "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`."
                        },
                        "tracks": {
                          "type": "array",
                          "minItems": 1,
                          "maxItems": 200,
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "asset_version_id": {
                                "type": "string",
                                "format": "uuid",
                                "description": "A finalized audio asset version."
                              },
                              "side": {
                                "enum": [
                                  "A",
                                  "B"
                                ],
                                "description": "Cassettes: the side the track plays on. Required for cassettes."
                              },
                              "title": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "pattern": "\\S",
                                "description": "Printed in tracklists."
                              },
                              "artist": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "pattern": "\\S",
                                "description": "Printed in tracklists."
                              }
                            },
                            "required": [
                              "asset_version_id"
                            ]
                          }
                        }
                      },
                      "required": [
                        "format",
                        "quantity",
                        "tracks"
                      ]
                    }
                  },
                  "rights_warranty": {
                    "const": true
                  },
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 300,
                    "pattern": "\\S"
                  },
                  "external_ref": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "pattern": "\\S",
                    "description": "Your own reference."
                  }
                },
                "required": [
                  "quote_id",
                  "shipping_service",
                  "items",
                  "rights_warranty"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The order, in `received`.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      },
      "get": {
        "operationId": "listOrders",
        "summary": "List orders, newest first",
        "description": "Needs `orders:read`.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Only orders in this state.",
            "schema": {
              "enum": [
                "received",
                "validating",
                "needs_attention",
                "materials_hold",
                "awaiting_payment",
                "released",
                "cancelled",
                "complete"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "starting_after",
            "in": "query",
            "required": false,
            "description": "The last order id of the previous page.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OrderSummary"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "object",
                    "data",
                    "has_more"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "operationId": "getOrder",
        "summary": "Get an order",
        "description": "Needs `orders:read`. The order with its current items, amounts and latest payment as separate objects.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/orders/{id}/revisions": {
      "post": {
        "operationId": "reviseOrder",
        "summary": "Fix an order that needs attention",
        "description": "Needs `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": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 100,
                    "items": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "format": {
                          "enum": [
                            "vinyl_12",
                            "vinyl_7",
                            "cassette",
                            "cd_jewel",
                            "cd_jacket"
                          ]
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 10000
                        },
                        "surfaces": {
                          "type": "object",
                          "maxProperties": 10,
                          "propertyNames": {
                            "pattern": "^[a-z][a-z0-9_]{1,39}$"
                          },
                          "additionalProperties": {
                            "type": "string",
                            "format": "uuid",
                            "description": "A finalized artwork asset version."
                          },
                          "description": "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`."
                        },
                        "tracks": {
                          "type": "array",
                          "minItems": 1,
                          "maxItems": 200,
                          "items": {
                            "type": "object",
                            "additionalProperties": false,
                            "properties": {
                              "asset_version_id": {
                                "type": "string",
                                "format": "uuid",
                                "description": "A finalized audio asset version."
                              },
                              "side": {
                                "enum": [
                                  "A",
                                  "B"
                                ],
                                "description": "Cassettes: the side the track plays on. Required for cassettes."
                              },
                              "title": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "pattern": "\\S",
                                "description": "Printed in tracklists."
                              },
                              "artist": {
                                "type": "string",
                                "minLength": 1,
                                "maxLength": 200,
                                "pattern": "\\S",
                                "description": "Printed in tracklists."
                              }
                            },
                            "required": [
                              "asset_version_id"
                            ]
                          }
                        }
                      },
                      "required": [
                        "format",
                        "quantity",
                        "tracks"
                      ]
                    }
                  },
                  "reason": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "pattern": "\\S"
                  },
                  "quote_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "shipping_service": {
                    "type": "string"
                  },
                  "rights_warranty": {
                    "const": true
                  }
                },
                "required": [
                  "items",
                  "rights_warranty"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The revised order, back in `validating`.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/orders/{id}/cancel": {
      "post": {
        "operationId": "cancelOrder",
        "summary": "Cancel an order",
        "description": "Needs `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": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The order.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "reason": {
                    "type": "string",
                    "pattern": "^[a-z][a-z0-9_]{0,63}$",
                    "examples": [
                      "changed_mind"
                    ]
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The cancelled order.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "description": "The order was already released (`order_released`, with `exception_id`), or another conflict.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/artwork_templates": {
      "get": {
        "operationId": "listArtworkTemplates",
        "summary": "Artwork templates",
        "description": "Needs `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": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Only this format's surfaces.",
            "schema": {
              "enum": [
                "vinyl_12",
                "vinyl_7",
                "cassette",
                "cd_jewel",
                "cd_jacket"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The current templates.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ArtworkTemplate"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "object",
                    "data",
                    "has_more"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/events": {
      "get": {
        "operationId": "listEvents",
        "summary": "Event history",
        "description": "Needs `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": [
          {
            "name": "order_id",
            "in": "query",
            "required": false,
            "description": "One order's events.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "after_sequence",
            "in": "query",
            "required": false,
            "description": "With order_id: events after this sequence number.",
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "starting_after",
            "in": "query",
            "required": false,
            "description": "Without order_id: events after this event.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Only events of this type.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z_]+\\.[a-z_]+$"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of events.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "object",
                    "data",
                    "has_more"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/billing": {
      "get": {
        "operationId": "getBilling",
        "summary": "Card on file",
        "description": "Needs `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": {
          "200": {
            "description": "Billing for this key's account and mode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Billing"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/billing/setup": {
      "post": {
        "operationId": "createBillingSetup",
        "summary": "Save a card",
        "description": "Needs `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`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "return_url": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https://",
                    "maxLength": 2000,
                    "description": "Where Stripe sends you after the card is saved."
                  },
                  "cancel_url": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https://",
                    "maxLength": 2000,
                    "description": "Where Stripe sends you if you leave without saving. Defaults to return_url."
                  }
                },
                "required": [
                  "return_url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The setup page.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSetup"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          },
          "503": {
            "description": "Billing is not available in this mode yet (`billing_unavailable`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/webhook_endpoints": {
      "post": {
        "operationId": "createWebhookEndpoint",
        "summary": "Add a webhook endpoint",
        "description": "Needs `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": [
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "format": "uri"
                  },
                  "event_types": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "enum": [
                        "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"
                      ]
                    }
                  },
                  "description": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "pattern": "\\S"
                  }
                },
                "required": [
                  "url"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The endpoint and its signing secret.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      },
      "get": {
        "operationId": "listWebhookEndpoints",
        "summary": "List webhook endpoints, newest first",
        "description": "Needs `webhooks:manage`. Enabled and disabled endpoints, without secrets.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "starting_after",
            "in": "query",
            "required": false,
            "description": "The last endpoint id of the previous page.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of endpoints.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookEndpoint"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "object",
                    "data",
                    "has_more"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/webhook_endpoints/{id}": {
      "get": {
        "operationId": "getWebhookEndpoint",
        "summary": "Get a webhook endpoint",
        "description": "Needs `webhooks:manage`. Without its secret.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The endpoint.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/webhook_endpoints/{id}/enable": {
      "post": {
        "operationId": "enableWebhookEndpoint",
        "summary": "Enable an endpoint",
        "description": "Needs `webhooks:manage`. Safe to repeat; takes no Idempotency-Key. Fails with `too_many_endpoints` when 10 are already enabled.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The endpoint.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/webhook_endpoints/{id}/disable": {
      "post": {
        "operationId": "disableWebhookEndpoint",
        "summary": "Disable an endpoint",
        "description": "Needs `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": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The endpoint.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/webhook_endpoints/{id}/rotate_secret": {
      "post": {
        "operationId": "rotateWebhookSecret",
        "summary": "Issue a new signing secret",
        "description": "Needs `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": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The endpoint.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "overlap_hours": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 168,
                    "default": 24
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The endpoint and its new secret.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointWithSecret"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/webhook_endpoints/{id}/deliveries": {
      "get": {
        "operationId": "listWebhookDeliveries",
        "summary": "An endpoint's deliveries, newest first",
        "description": "Needs `webhooks:manage`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The endpoint.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Only deliveries in this state.",
            "schema": {
              "enum": [
                "pending",
                "delivered",
                "abandoned"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "starting_after",
            "in": "query",
            "required": false,
            "description": "The last delivery id of the previous page.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of deliveries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "object": {
                      "const": "list"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookDelivery"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "object",
                    "data",
                    "has_more"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/webhook_deliveries/{id}": {
      "get": {
        "operationId": "getWebhookDelivery",
        "summary": "A delivery with every attempt",
        "description": "Needs `webhooks:manage`.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The delivery.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The delivery, with `attempts`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    },
    "/webhook_deliveries/{id}/replay": {
      "post": {
        "operationId": "replayWebhookDelivery",
        "summary": "Send a delivery again",
        "description": "Needs `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": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "The delivery.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKeyRequired"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The delivery as requeued, with `attempts`.",
            "headers": {
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookDelivery"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/E400"
          },
          "401": {
            "$ref": "#/components/responses/E401"
          },
          "403": {
            "$ref": "#/components/responses/E403"
          },
          "404": {
            "$ref": "#/components/responses/E404"
          },
          "409": {
            "$ref": "#/components/responses/E409"
          },
          "413": {
            "$ref": "#/components/responses/E413"
          },
          "415": {
            "$ref": "#/components/responses/E415"
          },
          "422": {
            "$ref": "#/components/responses/E422"
          },
          "429": {
            "$ref": "#/components/responses/E429"
          },
          "500": {
            "$ref": "#/components/responses/E500"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "A tb_test_ API key."
      }
    },
    "headers": {
      "IdempotentReplayed": {
        "description": "Present and true when this is the stored response of an earlier request.",
        "schema": {
          "const": "true"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "string",
          "pattern": "^[0-9]+$"
        }
      }
    },
    "parameters": {
      "IdempotencyKeyRequired": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "pattern": "^[\\x21-\\x7e]{1,255}$"
        }
      },
      "IdempotencyKeyOptional": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "schema": {
          "type": "string",
          "pattern": "^[\\x21-\\x7e]{1,255}$"
        }
      }
    },
    "responses": {
      "E400": {
        "description": "The body is not JSON, or the Idempotency-Key is missing or malformed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E401": {
        "description": "The API key is missing or not valid (`missing_api_key`, `invalid_api_key`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E403": {
        "description": "The key lacks a scope (`insufficient_scope`), or is a live key (`live_mode_unavailable`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E404": {
        "description": "No such resource for this key, or no such path.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E409": {
        "description": "The 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`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E413": {
        "description": "The body is over 2 MiB (`body_too_large`). It may be refused only after more of it was sent.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E415": {
        "description": "The body is not application/json.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E422": {
        "description": "The request is invalid; `field` names the problem, `code` says what it is.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E429": {
        "description": "Too 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.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "E500": {
        "description": "Our error. Retrying is safe with the same Idempotency-Key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Billing": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "object": {
            "const": "billing"
          },
          "payment_method": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "type": {
                    "const": "card"
                  },
                  "brand": {
                    "type": "string",
                    "examples": [
                      "visa"
                    ]
                  },
                  "last4": {
                    "type": "string",
                    "pattern": "^[0-9]{4}$"
                  },
                  "exp_month": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 12
                  },
                  "exp_year": {
                    "type": "integer"
                  },
                  "updated_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "required": [
                  "type",
                  "brand",
                  "last4",
                  "exp_month",
                  "exp_year",
                  "updated_at"
                ]
              }
            ]
          }
        },
        "required": [
          "object",
          "payment_method"
        ]
      },
      "BillingSetup": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "object": {
            "const": "billing_setup"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "object",
          "url",
          "expires_at"
        ]
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_]*$",
                "description": "A stable code, such as invalid_sha256."
              },
              "message": {
                "type": "string"
              },
              "field": {
                "type": "string"
              },
              "request_id": {
                "type": "string",
                "pattern": "^req_[0-9a-f]{32}$"
              },
              "exception_id": {
                "type": "string",
                "format": "uuid",
                "description": "With order_released: the exception opened for the cancel request."
              }
            },
            "required": [
              "code",
              "message",
              "request_id"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "AddressInput": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 200
          },
          "line1": {
            "type": "string",
            "maxLength": 200
          },
          "line2": {
            "type": "string",
            "maxLength": 200
          },
          "city": {
            "type": "string",
            "maxLength": 200
          },
          "region": {
            "type": "string",
            "maxLength": 200
          },
          "postal_code": {
            "type": "string",
            "maxLength": 200
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$"
          },
          "phone": {
            "type": "string",
            "maxLength": 200
          }
        },
        "required": [
          "name",
          "line1",
          "city",
          "postal_code",
          "country"
        ],
        "description": "Unknown fields are ignored."
      },
      "Address": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": {
            "type": "string"
          },
          "line1": {
            "type": "string"
          },
          "line2": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$"
          },
          "phone": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "line1",
          "city",
          "postal_code",
          "country"
        ]
      },
      "ShippingOption": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "service": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          },
          "min_days": {
            "type": "integer",
            "minimum": 0
          },
          "max_days": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "service",
          "amount_minor"
        ]
      },
      "Quote": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "quote"
          },
          "environment": {
            "enum": [
              "test",
              "live"
            ]
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "description": "ISO 4217 code, lowercase."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "position": {
                  "type": "integer",
                  "minimum": 1
                },
                "format": {
                  "enum": [
                    "vinyl_12",
                    "vinyl_7",
                    "cassette",
                    "cd_jewel",
                    "cd_jacket"
                  ]
                },
                "quantity": {
                  "type": "integer"
                },
                "runtime_seconds": {
                  "type": "integer"
                },
                "unit_price_minor": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "An amount in the currency's minor unit (cents for usd)."
                },
                "setup_fee_minor": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "An amount in the currency's minor unit (cents for usd)."
                },
                "amount_minor": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "An amount in the currency's minor unit (cents for usd)."
                }
              },
              "required": [
                "position",
                "format",
                "quantity",
                "runtime_seconds",
                "unit_price_minor",
                "setup_fee_minor",
                "amount_minor"
              ]
            }
          },
          "subtotal_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          },
          "shipping_options": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ShippingOption"
            }
          },
          "ship_to": {
            "$ref": "#/components/schemas/Address"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "environment",
          "currency",
          "items",
          "subtotal_minor",
          "shipping_options",
          "ship_to",
          "expires_at",
          "created_at"
        ]
      },
      "UploadCreated": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "upload"
          },
          "kind": {
            "enum": [
              "audio",
              "artwork"
            ]
          },
          "state": {
            "const": "created"
          },
          "upload": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "method": {
                "const": "PUT"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "expires_in": {
                "type": "integer",
                "description": "Seconds the URL stays valid."
              }
            },
            "required": [
              "method",
              "url",
              "expires_in"
            ]
          }
        },
        "required": [
          "id",
          "object",
          "kind",
          "state",
          "upload"
        ]
      },
      "UploadFinalized": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "upload"
          },
          "state": {
            "const": "finalized"
          },
          "asset_version_id": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "id",
          "object",
          "state",
          "asset_version_id"
        ]
      },
      "UploadProcessing": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "upload"
          },
          "state": {
            "const": "processing"
          }
        },
        "required": [
          "id",
          "object",
          "state"
        ]
      },
      "Upload": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "upload"
          },
          "kind": {
            "enum": [
              "audio",
              "artwork"
            ]
          },
          "state": {
            "enum": [
              "created",
              "processing",
              "finalized",
              "rejected"
            ]
          },
          "asset_version_id": {
            "type": "string",
            "format": "uuid",
            "description": "Once finalized."
          },
          "rejected_reason": {
            "type": "string",
            "description": "Once rejected: a stable code.",
            "examples": [
              "checksum_mismatch"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "kind",
          "state",
          "created_at"
        ]
      },
      "Amount": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "description": "ISO 4217 code, lowercase."
          },
          "subtotal_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          },
          "shipping_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          },
          "total_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          }
        },
        "required": [
          "currency",
          "subtotal_minor",
          "shipping_minor",
          "total_minor"
        ]
      },
      "Refund": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "enum": [
              "pending",
              "succeeded",
              "failed"
            ]
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "description": "ISO 4217 code, lowercase."
          },
          "reason": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "state",
          "amount_minor",
          "currency",
          "reason",
          "created_at"
        ]
      },
      "Payment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "enum": [
              "pending",
              "requires_action",
              "succeeded",
              "failed",
              "canceled",
              "unknown"
            ]
          },
          "amount_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          },
          "currency": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "description": "ISO 4217 code, lowercase."
          },
          "amount_received_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "An amount in the currency's minor unit (cents for usd)."
          },
          "currency_received": {
            "type": "string",
            "pattern": "^[a-z]{3}$",
            "description": "ISO 4217 code, lowercase."
          },
          "failure_code": {
            "type": "string"
          },
          "refunds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Refund"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "state",
          "amount_minor",
          "currency",
          "refunds",
          "created_at"
        ]
      },
      "Unit": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "unit"
          },
          "item_position": {
            "type": "integer",
            "minimum": 1
          },
          "serial": {
            "type": "integer",
            "minimum": 1,
            "description": "The unit's number within its item."
          },
          "state": {
            "enum": [
              "made",
              "passed",
              "scrapped",
              "packed",
              "shipped",
              "returned",
              "quarantined"
            ]
          },
          "replaces_unit_id": {
            "type": "string",
            "format": "uuid",
            "description": "Set on a remade unit: the scrapped unit it replaces."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "item_position",
          "serial",
          "state",
          "created_at"
        ]
      },
      "Shipment": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "shipment"
          },
          "state": {
            "enum": [
              "packing",
              "label_created",
              "handed_to_carrier",
              "voided",
              "in_transit",
              "delivered",
              "returned"
            ]
          },
          "carrier": {
            "type": "string"
          },
          "service": {
            "type": "string"
          },
          "tracking_number": {
            "type": "string"
          },
          "tracking_url": {
            "type": "string"
          },
          "unit_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The units in the shipment now. Empty once a voided label releases them."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "state_changed_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "state",
          "unit_ids",
          "created_at",
          "state_changed_at"
        ]
      },
      "ArtworkTemplate": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "artwork_template"
          },
          "format": {
            "enum": [
              "vinyl_12",
              "vinyl_7",
              "cassette",
              "cd_jewel",
              "cd_jacket"
            ]
          },
          "surface": {
            "type": "string",
            "description": "The key to use in an item's `surfaces`."
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "required": {
            "type": "boolean",
            "description": "The surface is printed on every unit."
          },
          "default_design": {
            "type": "string",
            "description": "Printed when you send no artwork for the surface. Missing when artwork is needed."
          },
          "status": {
            "enum": [
              "provisional",
              "approved"
            ],
            "description": "`provisional` until a print-and-fit proof approves the geometry."
          },
          "printer": {
            "enum": [
              "primera_bravo_4202",
              "epson_ecotank"
            ]
          },
          "trim": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "width_mm": {
                "type": "number"
              },
              "height_mm": {
                "type": "number"
              }
            },
            "required": [
              "width_mm",
              "height_mm"
            ]
          },
          "bleed_mm": {
            "type": "number",
            "description": "Extend artwork this far past the trim on every side."
          },
          "safe_mm": {
            "type": "number",
            "description": "Keep text and faces this far inside the trim."
          },
          "canvas": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "width_mm": {
                "type": "number"
              },
              "height_mm": {
                "type": "number"
              }
            },
            "required": [
              "width_mm",
              "height_mm"
            ],
            "description": "Trim plus bleed: the area your artwork must cover."
          },
          "folds": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "axis": {
                  "enum": [
                    "x",
                    "y"
                  ]
                },
                "at_mm": {
                  "type": "number"
                }
              },
              "required": [
                "axis",
                "at_mm"
              ]
            },
            "description": "Fold lines from the trim's top-left corner; `x` folds are vertical."
          },
          "mask": {
            "type": "object",
            "additionalProperties": true,
            "description": "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_zone": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "x_mm": {
                "type": "number"
              },
              "y_mm": {
                "type": "number"
              },
              "size_mm": {
                "type": "number"
              }
            },
            "required": [
              "x_mm",
              "y_mm",
              "size_mm"
            ],
            "description": "Where each unit's QR code prints, from the trim's top-left corner. Keep it plain."
          },
          "target_ppi": {
            "type": "integer"
          },
          "min_ppi": {
            "type": "integer"
          },
          "target_pixels": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "width": {
                "type": "integer"
              },
              "height": {
                "type": "integer"
              }
            },
            "required": [
              "width",
              "height"
            ],
            "description": "The smallest artwork that reaches `target_ppi` over the canvas. Larger files of the same proportions are fine."
          },
          "approved_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "format",
          "surface",
          "version",
          "label",
          "description",
          "required",
          "status",
          "printer",
          "trim",
          "bleed_mm",
          "safe_mm",
          "canvas",
          "folds",
          "target_ppi",
          "min_ppi",
          "target_pixels",
          "created_at"
        ]
      },
      "Finding": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "code": {
            "type": "string",
            "description": "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": {
            "enum": [
              "partner",
              "review"
            ]
          },
          "item_position": {
            "type": "integer",
            "minimum": 1
          },
          "track_position": {
            "type": "integer",
            "minimum": 1
          },
          "surface": {
            "type": "string",
            "description": "The artwork surface (such as `front_insert`) or cassette side (`side_a`, `side_b`) concerned."
          },
          "measured": {
            "type": "object",
            "additionalProperties": true,
            "description": "What was measured, e.g. `{ \"sample_rate\": 22050 }`."
          },
          "expected": {
            "type": "object",
            "additionalProperties": true,
            "description": "What is required, e.g. `{ \"min_sample_rate\": 44100 }`."
          },
          "review_state": {
            "enum": [
              "pending",
              "approved",
              "rejected"
            ],
            "description": "For `review` findings. In test mode reviews are approved at once."
          }
        },
        "required": [
          "code",
          "kind",
          "measured",
          "expected"
        ]
      },
      "Order": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "order"
          },
          "environment": {
            "enum": [
              "test",
              "live"
            ]
          },
          "state": {
            "enum": [
              "received",
              "validating",
              "needs_attention",
              "materials_hold",
              "awaiting_payment",
              "released",
              "cancelled",
              "complete"
            ]
          },
          "attention_reason": {
            "type": "string",
            "description": "Why the order needs attention, as a code: the first of `findings` you need to fix, or `price_commitment_expired`."
          },
          "title": {
            "type": "string"
          },
          "external_ref": {
            "type": "string"
          },
          "quote_id": {
            "type": "string",
            "format": "uuid"
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Finding"
            },
            "description": "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)."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "position": {
                  "type": "integer",
                  "minimum": 1
                },
                "format": {
                  "enum": [
                    "vinyl_12",
                    "vinyl_7",
                    "cassette",
                    "cd_jewel",
                    "cd_jacket"
                  ]
                },
                "quantity": {
                  "type": "integer"
                },
                "artwork_version_id": {
                  "type": "string",
                  "format": "uuid",
                  "description": "Only on items from before surfaces, for formats without artwork templates."
                },
                "surfaces": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "surface": {
                        "type": "string"
                      },
                      "asset_version_id": {
                        "type": "string",
                        "format": "uuid",
                        "description": "Your artwork. Missing when the default design prints."
                      },
                      "default_design": {
                        "type": "string",
                        "description": "Tapebloom's design printed when no artwork was sent."
                      },
                      "template": {
                        "type": "object",
                        "additionalProperties": false,
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "version": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "status": {
                            "enum": [
                              "provisional",
                              "approved"
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "version",
                          "status"
                        ],
                        "description": "The template version pinned when the item was submitted."
                      }
                    },
                    "required": [
                      "surface",
                      "template"
                    ]
                  }
                },
                "tracks": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                      "position": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "side": {
                        "enum": [
                          "A",
                          "B"
                        ]
                      },
                      "asset_version_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "recording_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "title": {
                        "type": "string"
                      },
                      "artist": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "position",
                      "asset_version_id",
                      "recording_id"
                    ]
                  }
                }
              },
              "required": [
                "position",
                "format",
                "quantity",
                "tracks"
              ]
            }
          },
          "ship_to": {
            "$ref": "#/components/schemas/Address"
          },
          "shipping": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "service": {
                "type": "string"
              },
              "amount_minor": {
                "type": "integer",
                "minimum": 0,
                "description": "An amount in the currency's minor unit (cents for usd)."
              }
            },
            "required": [
              "service",
              "amount_minor"
            ]
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "price_commitment_until": {
            "type": "string",
            "format": "date-time"
          },
          "rights_warranty_accepted_at": {
            "type": "string",
            "format": "date-time"
          },
          "payment": {
            "$ref": "#/components/schemas/Payment"
          },
          "units": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Unit"
            },
            "description": "Physical units made for the order, once released."
          },
          "shipments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Shipment"
            },
            "description": "The order is complete once the carrier has accepted shipments holding every unit it needs."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "environment",
          "state",
          "revision",
          "items",
          "created_at",
          "updated_at"
        ]
      },
      "OrderSummary": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "order"
          },
          "environment": {
            "enum": [
              "test",
              "live"
            ]
          },
          "state": {
            "enum": [
              "received",
              "validating",
              "needs_attention",
              "materials_hold",
              "awaiting_payment",
              "released",
              "cancelled",
              "complete"
            ]
          },
          "attention_reason": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "external_ref": {
            "type": "string"
          },
          "revision": {
            "type": "integer",
            "minimum": 1
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "environment",
          "state",
          "revision",
          "created_at",
          "updated_at"
        ]
      },
      "WebhookEndpoint": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "webhook_endpoint"
          },
          "environment": {
            "enum": [
              "test",
              "live"
            ]
          },
          "url": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "event_types": {
            "type": "array",
            "items": {
              "enum": [
                "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"
              ]
            },
            "description": "Missing when the endpoint receives every type."
          },
          "enabled": {
            "type": "boolean"
          },
          "previous_secret_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "During a rotation: when the previous secret stops signing."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "object",
          "environment",
          "url",
          "enabled",
          "created_at",
          "updated_at"
        ]
      },
      "WebhookEndpointWithSecret": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "webhook_endpoint"
          },
          "environment": {
            "enum": [
              "test",
              "live"
            ]
          },
          "url": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "event_types": {
            "type": "array",
            "items": {
              "enum": [
                "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"
              ]
            },
            "description": "Missing when the endpoint receives every type."
          },
          "enabled": {
            "type": "boolean"
          },
          "previous_secret_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "During a rotation: when the previous secret stops signing."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "secret": {
            "type": "string",
            "pattern": "^whsec_",
            "description": "The signing secret. Missing only from a replay made after the secret stopped signing."
          }
        },
        "required": [
          "id",
          "object",
          "environment",
          "url",
          "enabled",
          "created_at",
          "updated_at"
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "object": {
            "const": "webhook_delivery"
          },
          "environment": {
            "enum": [
              "test",
              "live"
            ]
          },
          "endpoint_id": {
            "type": "string",
            "format": "uuid"
          },
          "event_id": {
            "type": "string",
            "format": "uuid"
          },
          "event_type": {
            "enum": [
              "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"
            ]
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "state": {
            "enum": [
              "pending",
              "delivered",
              "abandoned"
            ]
          },
          "attempt_count": {
            "type": "integer",
            "minimum": 0
          },
          "next_attempt_at": {
            "type": "string",
            "format": "date-time",
            "description": "While pending: when the next attempt is due."
          },
          "deadline_at": {
            "type": "string",
            "format": "date-time",
            "description": "Retries stop here."
          },
          "last_status_code": {
            "type": "integer"
          },
          "last_error": {
            "type": "string"
          },
          "delivered_at": {
            "type": "string",
            "format": "date-time"
          },
          "replay_count": {
            "type": "integer",
            "minimum": 0
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "attempts": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "attempt_number": {
                  "type": "integer",
                  "minimum": 1
                },
                "signed_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "status_code": {
                  "type": "integer",
                  "minimum": 100,
                  "maximum": 599
                },
                "error": {
                  "enum": [
                    "timeout",
                    "network_error",
                    "blocked_address",
                    "redirect",
                    "invalid_url",
                    "invalid_response"
                  ]
                },
                "duration_ms": {
                  "type": "integer",
                  "minimum": 0
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              },
              "required": [
                "attempt_number",
                "signed_at",
                "created_at"
              ]
            }
          }
        },
        "required": [
          "id",
          "object",
          "environment",
          "endpoint_id",
          "event_id",
          "event_type",
          "order_id",
          "state",
          "attempt_count",
          "deadline_at",
          "replay_count",
          "created_at"
        ]
      },
      "Event": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "pattern": "^[a-z_]+\\.[a-z_]+$"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          },
          "environment": {
            "enum": [
              "test",
              "live"
            ]
          },
          "order_id": {
            "type": "string",
            "format": "uuid"
          },
          "sequence": {
            "type": "integer",
            "minimum": 1
          },
          "data": {
            "type": "object",
            "description": "The fields this event type exposes; always includes order_id, object and object_id."
          }
        },
        "required": [
          "id",
          "type",
          "occurred_at",
          "environment",
          "order_id",
          "sequence",
          "data"
        ]
      }
    }
  }
}
