themassprint-com Orders API

openapi: 3.2.0
info:
  title: massprint Orders API
  version: 1.0.0
  description: 'Print-on-demand for AI agents: upload a PDF, pay a Razorpay link, get a printed storybook delivered in India. MCP server (no key needed) at /mcp. Docs at /docs; index at /llms.txt.'
  contact:
    email: work@msomu.com
servers:
- url: https://themassprint.com
security:
- apiKey: []
- {}
tags:
- name: Orders
paths:
  /v1/orders:
    post:
      summary: Create a print order
      description: 'Validates PDF + address BEFORE minting any payment link. payment_link keys/anonymous: response carries payment_url. invoiced keys: order auto-confirms. Save order_token — shown once.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                upload_id:
                  type: string
                sku:
                  type: string
                  default: storybook
                  description: Optional; inferred from format (sticker-a3 → sticker-a3, greeting-card-a5 → greeting-card-a5, else storybook).
                format:
                  type: string
                  enum:
                  - paperback
                  - hardcover
                  - sticker-a3
                  - greeting-card-a5
                  description: 'paperback/hardcover: bound storybook. sticker-a3: single-sheet A3 portrait sticker / wall chart (exactly 1 page, 842×1191 pt). greeting-card-a5: folded A5 greeting card, one A4-landscape sheet printed duplex (exactly 2 pages, 859×612 pt incl. 3 mm bleed).'
                copies:
                  type: integer
                  minimum: 1
                  maximum: 20
                  default: 1
                email:
                  type: string
                  format: email
                address:
                  $ref: '#/components/schemas/Address'
                client_reference:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: 'Caller-owned idempotency key (e.g. your own order id). API-keyed callers replaying the same reference get HTTP 200 with the ORIGINAL order and deduplicated: true — never a second print. A canceled/refunded/expired order releases its reference. Anonymous callers may send it but only keyed callers get the dedupe guarantee.'
              required:
              - upload_id
              - format
              - email
              - address
      responses:
        '200':
          description: 'Replayed client_reference: the original order is returned, no new order is created. order_token is null — it was shown once, at the original creation.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
                  order_token:
                    type: 'null'
                  deduplicated:
                    type: boolean
                    enum:
                    - true
        '201':
          description: Order created
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
                  order_token:
                    type: string
        '422':
          description: Invalid fields or unprintable PDF
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Orders
      operationId: postV1Orders
      x-operation-id-source: derived
  /v1/orders/{id}:
    get:
      summary: Order status + tracking
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: token
        in: query
        required: false
        schema:
          type: string
        description: order_token (alternative to API-key/session auth)
      - name: X-Order-Token
        in: header
        required: false
        schema:
          type: string
        description: order_token as a header — preferred over ?token so it stays out of URLs/logs.
      responses:
        '200':
          description: Order
          content:
            application/json:
              schema:
                type: object
                properties:
                  order:
                    $ref: '#/components/schemas/Order'
        '403':
          description: Not the owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Orders
      operationId: getV1OrdersById
      x-operation-id-source: derived
  /v1/orders/{id}/cancel:
    post:
      summary: Cancel an order
      description: 'Any authorized caller may cancel while awaiting_payment. The API key that CREATED the order may also cancel it while confirmed or printing — stopping production before the press finishes. shipped and delivered can never be canceled; that is a refund conversation, not a cancel. Canceling moves no money, and it RELEASES the order''s client_reference: replaying that reference afterwards creates a new order and prints it. If the order changes status before the cancel lands, the answer is 409 not_cancellable naming the status it moved to — a cancel never reports success it did not achieve. The same two tiers apply to the MCP cancel_order tool.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: token
        in: query
        required: false
        schema:
          type: string
      - name: X-Order-Token
        in: header
        required: false
        schema:
          type: string
        description: order_token as a header (alternative to ?token).
      responses:
        '200':
          description: Canceled
        '409':
          description: Status does not allow canceling for this caller, or the order moved before the cancel landed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Orders
      operationId: postV1OrdersByIdCancel
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            resolution:
              type: string
              description: How the caller can recover.
            details: {}
          required:
          - code
          - message
    Order:
      type: object
      properties:
        order_id:
          type: string
        status:
          type: string
          enum:
          - awaiting_payment
          - confirmed
          - printing
          - shipped
          - delivered
          - expired
          - canceled
          - refunded
        sku:
          type: string
        format:
          type: string
          enum:
          - paperback
          - hardcover
          - sticker-a3
          - greeting-card-a5
        client_reference:
          type: string
          description: The caller-owned idempotency key this order was created with, echoed back.
        copies:
          type: integer
        page_count:
          type: integer
        amount:
          type: object
          properties:
            total_paise:
              type: integer
            display:
              type: string
            currency:
              type: string
        email:
          type: string
          format: email
        payment_mode:
          type: string
          enum:
          - payment_link
          - invoiced
        payment_url:
          type: string
          description: 'Present while awaiting_payment: the Razorpay link to pay.'
        payment_expires_at:
          type: string
        paid_at:
          type: string
        tracking:
          type: object
          properties:
            carrier:
              type: string
            awb:
              type: string
            url:
              type: string
              description: Clickable tracking link, when the shipper provided one.
        created_at:
          type: string
        updated_at:
          type: string
    Address:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        pincode:
          type: string
          pattern: ^[1-9][0-9]{5}$
          description: 6-digit India PIN
        phone:
          type: string
          description: India mobile, optional +91
      required:
      - name
      - line1
      - city
      - state
      - pincode
      - phone
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Platform API key (mp_live_...). Optional for one-off agent use.