openapi: 3.0.3
info:
  title: Admin Account / Address Stripe API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: "Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation failed\",\n    \"details\": { \"name\": [\"can't be blank\"] }\n  }\n}\n```\n"
  version: v3
servers:
- url: http://{defaultHost}
  variables:
    defaultHost:
      default: localhost:3000
tags:
- name: Stripe
paths:
  /api/v2/storefront/stripe/payment_intents:
    post:
      summary: Create a Stripe Payment Intent
      description: Create a Stripe Payment Intent using provided payment method. It creates a Stripe customer if not exists.
      tags:
      - Stripe
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                payment_intent:
                  type: object
                  properties:
                    amount:
                      type: number
                      description: The payment amount
                    stripe_payment_method_id:
                      type: string
                      description: Stripe Payment Method ID
                    off_session:
                      type: boolean
                      description: If the payment is off-session (eq. payment method from setup intent)
              required:
              - payment_intent
      operationId: create-stripe-payment-intent
      responses:
        '200':
          $ref: '#/components/responses/StripePaymentIntent'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
      security:
      - orderToken: []
  /api/v2/storefront/stripe/payment_intents/{id}:
    get:
      summary: Return a Stripe Payment Intent
      description: Returns the Payment Intent information
      tags:
      - Stripe
      operationId: show-stripe-payment-intent
      responses:
        '200':
          $ref: '#/components/responses/StripePaymentIntent'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
      security:
      - orderToken: []
    patch:
      summary: Updates Stripe Payment Intent
      description: Updates the payment intent with new `amount` and `stripe_payment_method_id`
      tags:
      - Stripe
      operationId: update-stripe-payment-intent
      security:
      - orderToken: []
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                payment_intent:
                  type: object
                  properties:
                    amount:
                      type: number
                      description: A new payment amount
                    stripe_payment_method_id:
                      type: string
                      description: A new Stripe Payment Method ID
              required:
              - payment_intent
      responses:
        '200':
          $ref: '#/components/responses/StripePaymentIntent'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
  /api/v2/storefront/stripe/payment_intents/{id}/confirm:
    patch:
      summary: Mark the payment intent as confirmed, and move the order to the complete state
      description: This endpoint is used to complete the order with succeeded payment intent. First it will check if the payment intent has `status` `succeeded`, if yes, then it will move the order to the complete state.
      tags:
      - Stripe
      operationId: confirm-stripe-payment-intent
      security:
      - orderToken: []
      responses:
        '200':
          $ref: '#/components/responses/StripePaymentIntent'
        '403':
          $ref: '#/components/responses/403Forbidden'
        '404':
          $ref: '#/components/responses/404NotFound'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
  /api/v2/storefront/stripe/setup_intents:
    post:
      summary: Create a Stripe Setup Intent
      description: First, this endpoint creates a customer in Stripe (if it doesn't already exist), then it creates an Ephemeral Key for the customer, and finally, it creates a Setup Intent for the customer.
      tags:
      - Stripe
      operationId: create-stripe-setup-intent
      responses:
        '200':
          $ref: '#/components/responses/StripeSetupIntent'
        '422':
          $ref: '#/components/responses/422UnprocessableEntity'
components:
  responses:
    403Forbidden:
      description: 403 Forbidden - You are not authorized to access this page.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: You are not authorized to access this page.
                default: You are not authorized to access this page.
          examples:
            403 Example:
              value:
                error: You are not authorized to access this page.
    404NotFound:
      description: 404 Not Found - Resource not found.
      content:
        application/vnd.api+json:
          schema:
            properties:
              error:
                type: string
                example: The resource you were looking for could not be found.
                default: The resource you were looking for could not be found.
          examples:
            404 Example:
              value:
                error: The resource you were looking for could not be found.
    422UnprocessableEntity:
      description: 422 Unprocessable Entity
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            422 Example:
              value:
                error: Example is invalid
                errors:
                  example:
                  - Example is invalid
    StripeSetupIntent:
      description: 200 Success - Returns the `customer_id` of the authenticated user, created ephemeral key's secret and client secret of the created setup intent.
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              customer_id:
                type: string
                description: 'Stripe''s customer ID of the authenticated user (or new one if unauthenticated).

                  '
              ephemeral_key_secret:
                type: string
                description: 'Secret of the created ephemeral key.

                  '
              setup_intent_client_secret:
                type: string
                description: 'Client secret of the created setup intent

                  '
            required:
            - customer_id
            - ephemeral_key_secret
            - setup_intent_client_secret
          examples:
            Stripe Setup Intent:
              value:
                customer_id: cus_Q9uqUz6gVQFku2
                ephemeral_key_secret: ek_test_YWNjdF8xTGtSb1lJaFIwZ0llZ0llyG1LbFhsVU9XWHY1SlNyMXRKVzNJb0hyQ2JZam1HY28_007lGgvGaA
                setup_intent_client_secret: seti_1PJb0hIhR0gIegIeZYQQuxpH_secret_Q9uqLuTAvIJQSK1SFS6OaxJMRpe9s7R
    StripePaymentIntent:
      description: 200 Success - Returns the Stripe Payment Intent with the Stripe ID, client key, ephemeral_key, customer_id, amount and Stripe Payment Method ID.
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  id:
                    type: string
                    example: 980a80d5-f51b-4065-b3a0-622fc5cb6bf6
                  type:
                    type: string
                    default: payment_intent
                  attributes:
                    type: object
                    properties:
                      stripe_id:
                        type: string
                        description: The Stripe internal ID of the Payment Intent
                      client_secret:
                        type: string
                        description: 'The client secret can be used to complete a payment from your frontend. It should not be stored, logged, or exposed to anyone other than the customer. Make sure that you have TLS enabled on any page that includes the client secret.

                          '
                      ephemeral_key_secret:
                        type: string
                        description: 'Secret of the created ephemeral key.

                          '
                      customer_id:
                        type: string
                        description: 'Stripe''s customer ID of the authenticated user (or new one if unauthenticated).

                          '
                      amount:
                        type: number
                        description: The payment amount
                      stripe_payment_method_id:
                        type: string
                        description: 'This is the same stripe_payment_method_id that was sent in the parameters. It can be used to confirm Stripe intent that was not confirmed before

                          '
          examples:
            Stripe Payment Intent:
              value:
                data:
                  id: 980a80d5-f51b-4065-b3a0-622fc5cb6bf6
                  type: payment_intent
                  attributes:
                    stripe_id: pi_3QhUuj2ESifGlJez0ADSS4tu
                    client_secret: pi_3KQRG2DcAgmy0ota09WCW6nf_secret_8XTxRbOyg7oEkvvIOvnP75dRw
                    ephemeral_key_secret: ek_test_YWNjdF8xTGtSb1lJaFIwZ0llZ0llyG1LbFhsVU9XWHY1SlNyMXRKVzNJb0hyQ2JZam1HY28_007lGgvGaA
                    customer_id: cus_Q9uqUz6gVQFku2
                    amount: '44.0'
                    stripe_payment_method_id: pm_1Qedd42ESifGlJez0IOx5AZ3
  schemas:
    Error:
      x-internal: false
      title: Error
      type: object
      properties:
        error:
          type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: x-spree-api-key
      in: header
      description: Secret API key for admin access
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
- name: Products & Catalog
  tags:
  - Products
  - Variants
  - Option Types
  - Custom Fields
  - Channels
- name: Pricing
  tags:
  - Pricing
  - Markets
- name: Orders & Fulfillment
  tags:
  - Orders
  - Payments
  - Fulfillments
  - Refunds
- name: Customers
  tags:
  - Customers
  - Customer Groups
- name: Promotions & Gift Cards
  tags:
  - Promotions
  - Gift Cards
- name: Data
  tags:
  - Exports
- name: Configuration
  tags:
  - Settings
  - Stock Locations
  - Payment Methods
  - Staff
  - API Keys
  - Allowed Origins
  - Webhooks