> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload a purchase order document

> Prepares an upload for the buyer's signed purchase order document. Send the
file's metadata, then `PUT` the bytes to `upload.url` with exactly
`upload.headers`, and attach the file by sending the returned `signed_id` as
`po_document_signed_id` on a cart update. Files are stored privately.
`checksum` is the file's MD5 digest, base64-encoded. Returns 422 when the
declared size or type is not accepted for a purchase order.




## OpenAPI

````yaml /api-reference/store.yaml post /api/v3/store/carts/{cart_id}/po_document
openapi: 3.0.3
info:
  title: Store API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: >
    Spree Store API v3 - Customer-facing storefront API for building headless
    commerce experiences.


    ## Authentication


    The Store API uses two authentication methods:


    ### API Key (Required)

    All requests must include a publishable API key in the `x-spree-api-key`
    header.


    ### JWT Bearer Token (For authenticated customers)

    After login, include the JWT token in the `Authorization: Bearer <token>`
    header.


    ### Order Token (For guest checkout)

    When creating an order, a `token` is returned. Include this in the
    `x-spree-token` header

    for guest access to that specific order.


    ## Response Format


    All responses are JSON. List endpoints return paginated responses with
    `data` and `meta` keys.


    ## Error Handling


    Errors return a consistent format:

    ```json

    {
      "error": {
        "code": "record_not_found",
        "message": "Product not found"
      }
    }

    ```
  version: v3
servers:
  - url: http://{defaultHost}
    variables:
      defaultHost:
        default: localhost:3000
security: []
tags:
  - name: Authentication
    description: Customer authentication (login, logout, token refresh)
  - name: Product Catalog
    description: Products and categories
  - name: Carts
    description: Shopping cart management
  - name: Orders
    description: Order lookup
  - name: Customers
    description: Customer account, addresses, saved payment methods, and order history
  - name: Markets
    description: Markets, countries, currencies, and locales
  - name: Wishlists
    description: Customer wishlists
  - name: Newsletter Subscribers
    description: Guest and customer newsletter subscriptions (double opt-in)
  - name: Policies
    description: Store policies (return policy, privacy policy, terms of service)
  - name: Digitals
    description: Digital product downloads
paths:
  /api/v3/store/carts/{cart_id}/po_document:
    parameters:
      - name: cart_id
        in: path
        required: true
        description: Cart prefixed ID
        schema:
          type: string
    post:
      tags:
        - Carts
      summary: Upload a purchase order document
      description: >
        Prepares an upload for the buyer's signed purchase order document. Send
        the

        file's metadata, then `PUT` the bytes to `upload.url` with exactly

        `upload.headers`, and attach the file by sending the returned
        `signed_id` as

        `po_document_signed_id` on a cart update. Files are stored privately.

        `checksum` is the file's MD5 digest, base64-encoded. Returns 422 when
        the

        declared size or type is not accepted for a purchase order.
      parameters:
        - name: x-spree-api-key
          in: header
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          required: false
          schema:
            type: string
        - name: x-spree-token
          in: header
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePoDocumentParams'
        required: true
      responses:
        '201':
          description: upload target created
          content:
            application/json:
              example:
                signed_id: >-
                  eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--a9cd29e72a70654182038480207bd929343f6a07
                filename: purchase-order.pdf
                content_type: application/pdf
                byte_size: 48210
                visibility: private
                expires_at: '2026-01-16T12:00:00.000Z'
                upload:
                  method: PUT
                  url: >-
                    http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiIwc3NuNW5kM3RneWtwcWJndXdybGprZjNwbjc4IiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjQ4MjEwLCJjaGVja3N1bSI6IjVXMjhrY2ZxcDlLMGY1djRZN2VyUkE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--d1ccdf3e94900f0c8f62feb07f43a3d33eb3b0df
                  headers:
                    Content-Type: application/pdf
              schema:
                $ref: '#/components/schemas/FileUpload'
      security:
        - api_key: []
          bearer_auth: []
components:
  schemas:
    CreatePoDocumentParams:
      type: object
      properties:
        filename:
          type: string
        content_type:
          type: string
        byte_size:
          type: integer
        checksum:
          type: string
          description: >-
            Base64-encoded MD5 digest of the file; the storage service checks
            the bytes against it.
      required:
        - filename
        - content_type
        - byte_size
        - checksum
    FileUpload:
      type: object
      properties:
        signed_id:
          type: string
        filename:
          type: string
        content_type:
          type: string
        byte_size:
          type: number
        visibility:
          type: string
          enum:
            - public
            - private
        expires_at:
          type: string
        upload:
          allOf:
            - $ref: '#/components/schemas/FileUploadTarget'
          nullable: true
      required:
        - signed_id
        - filename
        - content_type
        - byte_size
        - visibility
        - expires_at
        - upload
      x-typelizer: true
    FileUploadTarget:
      type: object
      properties:
        method:
          type: string
        url:
          type: string
        headers:
          type: object
      required:
        - method
        - url
        - headers
      x-typelizer: true
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Publishable API key for store access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for authenticated customers

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.