Resolve Orders API

openapi: 3.0.0
info:
  title: Resolve API Reference Access Keys Orders API
  version: V5
  description: 'API Support: [accounts@resolvepay.com](mailto:accounts@resolvepay.com?subject=API)


    Legacy (v2) API documentation: [https://app.resolvepay.com/docs/api/v2](https://app.resolvepay.com/docs/api/v2)

    '
servers:
- url: https://app-sandbox.resolvepay.com/api
  description: Sandbox server
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Orders
  x-displayName: Orders
  description: 'An order represents an authorization of credit for a customer transaction. Once authorized, an order can be partially or fully captured as goods or services are fulfilled, or canceled if the transaction does not proceed.

    '
paths:
  /orders:
    get:
      summary: List orders
      operationId: listOrders
      description: Return a paginated list of orders.
      parameters:
      - name: limit
        schema:
          type: integer
          default: 100
          maximum: 100
          minimum: 1
        in: query
        description: Limit the number of orders returned.
      - name: page
        schema:
          type: string
          default: '1'
        in: query
        description: Specify the page of orders returned.
      - name: filter
        explode: true
        style: deepObject
        schema:
          type: object
          properties:
            status:
              type: object
              properties:
                eq:
                  type: string
            order_number:
              type: object
              properties:
                eq:
                  type: string
            po_number:
              type: object
              properties:
                eq:
                  type: string
            customer_id:
              type: object
              properties:
                eq:
                  type: string
            authorized_at:
              type: object
              properties:
                eq:
                  type: string
                  format: date-time
                gt:
                  type: string
                  format: date-time
                lt:
                  type: string
                  format: date-time
                gte:
                  type: string
                  format: date-time
                lte:
                  type: string
                  format: date-time
            amount_authorized:
              type: object
              properties:
                eq:
                  type: number
                gt:
                  type: number
                lt:
                  type: number
                gte:
                  type: number
                lte:
                  type: number
            amount_captured:
              type: object
              properties:
                eq:
                  type: number
                gt:
                  type: number
                lt:
                  type: number
                gte:
                  type: number
                lte:
                  type: number
            amount_canceled:
              type: object
              properties:
                eq:
                  type: number
                gt:
                  type: number
                lt:
                  type: number
                gte:
                  type: number
                lte:
                  type: number
            amount_remaining:
              type: object
              properties:
                eq:
                  type: number
                gt:
                  type: number
                lt:
                  type: number
                gte:
                  type: number
                lte:
                  type: number
        in: query
        description: "Filter orders by the specified fields.\n\nFilter semantics: `filter[field][operator]=value`.\n\nAvailable filter operators:\n- `eq` - equal (=)\n- `gt` - greater than (>)\n- `gte` - greater than or equal (>=)\n- `lt` - less than (<)\n- `lte` - less than or equal (<=)\n\nFiltering is allowed by the following fields:\n  - `status` (`eq`)\n  - `order_number` (`eq`)\n  - `po_number` (`eq`)\n  - `customer_id` (`eq`)\n  - `authorized_at` (`eq`, `gt`, `lt`, `gte`, `lte`)\n  - `amount_authorized` (`eq`, `gt`, `lt`, `gte`, `lte`)\n  - `amount_captured` (`eq`, `gt`, `lt`, `gte`, `lte`)\n  - `amount_canceled` (`eq`, `gt`, `lt`, `gte`, `lte`)\n  - `amount_remaining` (`eq`, `gt`, `lt`, `gte`, `lte`)\n\nExample: `filter[status][eq]=authorized`\n\nNote: filter with the `eq` operator is equivalent to `filter[field]=value`\n"
      responses:
        '200':
          $ref: '#/components/responses/OrderListResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Orders
    post:
      summary: Create an order
      operationId: createOrder
      description: Authorize a new order for a customer.
      requestBody:
        $ref: '#/components/requestBodies/OrderCreateRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/OrderResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Orders
  /orders/{order_id}:
    get:
      summary: Fetch an order
      operationId: fetchOrder
      description: Retrieve an existing order by its ID.
      parameters:
      - name: order_id
        schema:
          type: string
        in: path
        required: true
        description: ID of the order to retrieve.
      responses:
        '200':
          $ref: '#/components/responses/OrderResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Orders
    put:
      summary: Update an order
      operationId: updateOrder
      description: Update an authorized order's amount, order number, PO number, line items, or metadata. At least one field must be provided.
      parameters:
      - name: order_id
        schema:
          type: string
        in: path
        required: true
        description: ID of the order to update.
      requestBody:
        $ref: '#/components/requestBodies/OrderUpdateRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/OrderResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Orders
  /orders/{order_id}/capture:
    post:
      summary: Capture an order
      operationId: captureOrder
      description: Capture an authorized order. An order can be captured multiple times up to the full authorized amount.
      parameters:
      - name: order_id
        schema:
          type: string
        in: path
        required: true
        description: ID of the order to capture.
      requestBody:
        $ref: '#/components/requestBodies/OrderCaptureRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/OrderResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Orders
  /orders/{order_id}/cancel:
    post:
      summary: Cancel an order
      operationId: cancelOrder
      description: Cancel an authorized order, releasing any remaining authorized amount. If the order has been partially captured, only the uncaptured portion of the authorization is canceled — previously captured amounts are not affected.
      parameters:
      - name: order_id
        schema:
          type: string
        in: path
        required: true
        description: ID of the order to cancel.
      responses:
        '200':
          $ref: '#/components/responses/OrderResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Orders
components:
  schemas:
    OrderListResponse:
      type: object
      properties:
        count:
          type: integer
          example: 1
        limit:
          type: integer
          example: 100
        page:
          type: integer
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/OrderListItem'
    OrderCaptureEvent:
      type: object
      properties:
        amount:
          type: number
          format: double
          example: 500
          description: Amount captured in this capture event in USD.
        idempotency_key:
          type: string
          example: capture-2024-001
          description: Idempotency key used for this capture.
        processed_at:
          type: string
          format: date-time
          example: '2024-01-15T10:00:00.000Z'
          description: Timestamp when this capture was processed.
        invoice_id:
          type: string
          example: INabc123
          description: ID of the merchant invoice associated with this capture.
    OrderCreateRequest:
      type: object
      required:
      - amount
      - customer_id
      - line_items
      properties:
        amount:
          type: number
          format: double
          minimum: 0
          example: 1000
          description: Amount to authorize for the order in USD.
        customer_id:
          type: string
          example: X50sgfRd
          description: Unique identifier of the customer placing the order.
        line_items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderLineItem'
          description: Line items for the order. At least one item is required.
        order_number:
          type: string
          example: '5055'
          description: Your internal order number.
        po_number:
          type: string
          example: PO-555
          description: Purchase order number.
        advance_requested:
          type: boolean
          example: false
          description: Whether to request an advance on this order.
        source:
          type: string
          example: checkout
          description: Source channel creating the order.
        metadata:
          type: object
          additionalProperties: true
          example:
            internal_ref: ref-001
          description: Custom metadata to attach to the order.
    OrderLineItem:
      type: object
      additionalProperties: true
      properties:
        name:
          type: string
          example: Widget A
          description: Name or description of the line item.
        quantity:
          type: number
          example: 2
          description: Quantity of units.
        unit_price:
          type: number
          format: double
          example: 50
          description: Price per unit in USD.
        sku:
          type: string
          example: ABC-123
          description: SKU or product identifier.
        total_price:
          type: number
          format: double
          example: 100
          description: Total price for this line item in USD. Defaults to unit_price × quantity if omitted.
        type:
          type: string
          example: product
          description: 'Line item type. Common values: `product`, `shipping`, `subtotal`.'
        tax_amount:
          type: number
          format: double
          example: 8.5
          description: Tax amount for this line item in USD.
    OrderListItem:
      type: object
      properties:
        id:
          type: string
          example: ORDlaE5wbg0
          description: Unique identifier for the order.
        checkout_id:
          type: string
          example: CHKabc123
          description: ID of the checkout session associated with this order.
        number:
          type: string
          example: ord_100001
          description: Order number identifier.
        po_number:
          type: string
          example: PO-555
          description: Purchase order number associated with the order.
        advance_requested:
          type: boolean
          example: false
          description: Whether an advance was requested for this order.
        source:
          type: string
          example: checkout
          description: Source channel that created the order.
        status:
          type: string
          example: authorized
          description: Current status of the order.
        amount_authorized:
          type: number
          format: double
          example: 1000
          description: Total authorized amount for the order in USD.
        amount_captured:
          type: number
          format: double
          example: 500
          description: Total captured amount for the order in USD.
        amount_canceled:
          type: number
          format: double
          example: 0
          description: Total canceled amount for the order in USD.
        amount_remaining:
          type: number
          format: double
          example: 500
          description: Remaining authorized amount available for capture in USD.
        first_captured_at:
          type: string
          format: date-time
          example: '2024-01-15T10:00:00.000Z'
          nullable: true
          description: Timestamp of the first capture event.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItem'
          description: Line items associated with the order.
        authorization_expires_at:
          type: string
          format: date-time
          example: '2024-02-15T10:00:00.000Z'
          description: Timestamp when the authorization expires.
        authorization_expiry_source:
          type: string
          example: system
          description: Source that determined the authorization expiry.
        authorized_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          description: Timestamp when the order was authorized.
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T10:00:00.000Z'
          description: Timestamp when the order was last updated.
        customer:
          $ref: '#/components/schemas/OrderCustomer'
    UnauthorizedError:
      type: object
      title: Unauthorized error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A short string, describing error details
              example: Invalid merchant credentials
            type:
              type: string
              description: A short string, describing error type
              enum:
              - authentication_error
              example: authentication_error
    NotFoundError:
      type: object
      title: Not found error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A short string, describing error details
              example: '[entity] not found'
            type:
              type: string
              description: A short string, describing error type
              enum:
              - not_found_error
              example: not_found_error
    ValidationError:
      type: object
      title: Validation error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A short string, describing error details
              example: Validation error
            type:
              type: string
              description: A short string, describing error type
              enum:
              - validation_error
              example: validation_error
            details:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                    example: path.to.field
                    description: Path to the field failed validation
                  message:
                    type: string
                    example: '`[field]` is required'
                    description: Detailed description of the error
    OrderCaptureRequest:
      type: object
      required:
      - amount
      - idempotency_key
      properties:
        amount:
          type: number
          format: double
          minimum: 0
          example: 500
          description: Amount to capture in USD. Must not exceed the remaining authorized amount.
        idempotency_key:
          type: string
          example: capture-2024-001
          description: Unique key to ensure idempotent capture requests.
        number:
          type: string
          example: inv_100001
          description: Invoice or shipment number for this capture.
        merchant_invoice_url:
          type: string
          format: uri
          example: https://example.com/invoice.pdf
          description: URL of the merchant invoice PDF. Provide either this or `line_items`, not both.
        line_items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderLineItem'
          description: Line items for this capture. Provide either this or `merchant_invoice_url`, not both.
    OrderCustomer:
      type: object
      properties:
        id:
          type: string
          example: X50sgfRd
          description: Unique identifier of the customer.
        name:
          type: string
          example: Acme Corp
          description: Business name of the customer.
        remaining_credit:
          type: number
          format: double
          example: 5000
          description: Remaining available credit for the customer in USD.
    InvalidRequestError:
      type: object
      title: Invalid request error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A short string, describing error details
              example: '[Invalid request message]'
            type:
              type: string
              description: A short string, describing error type
              enum:
              - invalid_request
              example: invalid_request
    OrderUpdateRequest:
      type: object
      minProperties: 1
      properties:
        amount:
          type: number
          format: double
          minimum: 0
          example: 1200
          description: Updated authorization amount in USD.
        order_number:
          type: string
          example: '5055'
          description: Updated internal order number.
        po_number:
          type: string
          example: PO-555
          description: Updated purchase order number.
        line_items:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderLineItem'
          description: Updated line items for the order.
    Order:
      type: object
      properties:
        id:
          type: string
          example: ORDlaE5wbg0
          description: Unique identifier for the order.
        checkout_id:
          type: string
          example: CHKabc123
          description: ID of the checkout session associated with this order.
        number:
          type: string
          example: ord_100001
          description: Order number identifier.
        po_number:
          type: string
          example: PO-555
          description: Purchase order number associated with the order.
        advance_requested:
          type: boolean
          example: false
          description: Whether an advance was requested for this order.
        source:
          type: string
          example: checkout
          description: Source channel that created the order.
        status:
          type: string
          example: authorized
          description: Current status of the order.
        amount_authorized:
          type: number
          format: double
          example: 1000
          description: Total authorized amount for the order in USD.
        amount_captured:
          type: number
          format: double
          example: 500
          description: Total captured amount for the order in USD.
        amount_canceled:
          type: number
          format: double
          example: 0
          description: Total canceled amount for the order in USD.
        amount_remaining:
          type: number
          format: double
          example: 500
          description: Remaining authorized amount available for capture in USD.
        first_captured_at:
          type: string
          format: date-time
          example: '2024-01-15T10:00:00.000Z'
          nullable: true
          description: Timestamp of the first capture event.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItem'
          description: Line items associated with the order.
        authorization_expires_at:
          type: string
          format: date-time
          example: '2024-02-15T10:00:00.000Z'
          description: Timestamp when the authorization expires.
        authorization_expiry_source:
          type: string
          example: system
          description: Source that determined the authorization expiry.
        capture_events:
          type: array
          items:
            $ref: '#/components/schemas/OrderCaptureEvent'
          description: List of capture events for this order.
        authorized_at:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
          description: Timestamp when the order was authorized.
        updated_at:
          type: string
          format: date-time
          example: '2024-01-15T10:00:00.000Z'
          description: Timestamp when the order was last updated.
        customer:
          $ref: '#/components/schemas/OrderCustomer'
    RateLimitError:
      type: object
      title: Rate limit error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: A short string, describing error details
              example: Too many requests
            type:
              type: string
              description: A short string, describing error type
              enum:
              - rate_limit_error
              example: rate_limit_error
  requestBodies:
    OrderCaptureRequestBody:
      description: Fields for capturing an authorized order.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrderCaptureRequest'
    OrderCreateRequestBody:
      description: Fields for creating a new order.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrderCreateRequest'
    OrderUpdateRequestBody:
      description: Fields to update on an authorized order. At least one field must be provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrderUpdateRequest'
  responses:
    InvalidRequestOrValidationResponse:
      description: Bad request error
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ValidationError'
            - $ref: '#/components/schemas/InvalidRequestError'
    UnauthorizedResponse:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    OrderListResponse:
      description: A paginated list of orders.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrderListResponse'
    RateLimitResponse:
      description: Rate limit error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
    OrderResponse:
      description: An object representing an order.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Order'
    NotFoundResponse:
      description: Not found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
  securitySchemes:
    basicAuth:
      description: HTTP Basic Auth using `merchant_id` as username and the merchant secret key as password.
      type: http
      scheme: basic
    bearerAuth:
      description: Bearer token authentication using an OAuth access token minted for an API access key created in Merchant Dashboard.
      type: http
      scheme: bearer
      bearerFormat: JWT