Spree Commerce Digitals API

openapi: 3.2.0
info:
  title: Store Digitals 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.\n\n## Authentication\n\nThe Store API uses two authentication methods:\n\n### API Key (Required)\nAll requests must include a publishable API key in the `x-spree-api-key` header.\n\n### JWT Bearer Token (For authenticated customers)\nAfter login, include the JWT token in the `Authorization: Bearer <token>` header.\n\n### Order Token (For guest checkout)\nWhen creating an order, a `token` is returned. Include this in the `x-spree-token` header\nfor guest access to that specific order.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"record_not_found\",\n    \"message\": \"Product not found\"\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Digitals
  description: Digital product downloads
paths:
  /api/v3/store/digitals/{token}:
    get:
      summary: Download a digital product
      tags:
      - Digitals
      description: 'Downloads a digital product file using the digital link token.

        The token is provided via the `download_url` field on digital links

        returned with order line items. No API key or authentication required —

        the token itself grants access.

        Each download increments the access counter. Downloads may be limited by

        store settings (number of downloads and/or time-based expiration).

        '
      parameters:
      - name: token
        in: path
        required: true
        description: Digital link token
        schema:
          type: string
      responses:
        '200':
          description: file downloaded
          content:
            application/json: {}
        '403':
          description: download link expired or limit exceeded
          content:
            application/json:
              example:
                error:
                  code: digital_link_expired
                  message: Download link expired or invalid
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: digital link not found
          content:
            application/json:
              example:
                error:
                  code: record_not_found
                  message: Digital link not found
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: record_not_found
            message:
              type: string
              example: Record not found
            details:
              type:
              - object
              - 'null'
              description: Field-specific validation errors
              example:
                name:
                - is too short
                - is required
                email:
                - is invalid
          required:
          - code
          - message
      required:
      - error
      example:
        error:
          code: validation_error
          message: Validation failed
          details:
            name:
            - is too short
            email:
            - is invalid
  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
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Product Catalog
  tags:
  - Product Catalog
- name: Carts
  tags:
  - Carts
- name: Orders
  tags:
  - Orders
- name: Customers
  tags:
  - Customers
- name: Markets
  tags:
  - Markets
- name: Wishlists
  tags:
  - Wishlists
- name: Newsletter Subscribers
  tags:
  - Newsletter Subscribers
- name: Policies
  tags:
  - Policies
- name: Digitals
  tags:
  - Digitals