Resolve Shipments API

openapi: 3.2.0
info:
  title: Resolve Shipments API
  x-refined-note:
  - x-logo differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Shipments across 2 of this provider''s published API definitions: resolve-merchant-api-openapi.yaml, resolve-partners-api-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app-sandbox.resolvepay.com/api
  description: Sandbox server
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Shipments
  x-displayName: Shipments
  description: A shipment represents the fulfillment of goods or services for an invoice.
paths:
  /shipments:
    get:
      summary: List Shipments
      operationId: listShipments
      parameters:
      - name: merchant_invoice_id
        schema:
          type: string
        in: query
        description: Filter shipments by specific merchant invoice ID.
        example: inv_1234567890abcdef
      - name: fulfillment_method
        schema:
          type: string
          enum:
          - shipping_provider
          - self_delivery
          - customer_pickup
          - services_only
        in: query
        description: Filter shipments by fulfillment method.
        example: shipping_provider
      - name: verification_status
        schema:
          type: string
          enum:
          - verified
          - pending
        in: query
        description: Filter shipments by verification status.
        example: verified
      - name: shipment_courier
        schema:
          type: string
        in: query
        description: Filter shipments by shipping courier.
        example: ups
      - name: limit
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        in: query
        description: Number of results to return per page (1-100).
        example: 25
      - name: starting_after
        schema:
          type: string
        in: query
        description: Pagination cursor for fetching results after a specific shipment ID.
        example: ship_1234567890abcdef
      - name: ending_before
        schema:
          type: string
        in: query
        description: Pagination cursor for fetching results before a specific shipment ID.
        example: ship_9876543210fedcba
      - name: search
        schema:
          type: string
        in: query
        description: Search term to filter shipments across multiple fields.
        example: 1Z123E45678901234
      - name: searchBy
        schema:
          type: string
          enum:
          - tracking_number
          - courier
          - id
          - merchant_invoice_id
        in: query
        description: Specific field to search within.
        example: tracking_number
      - name: sort
        schema:
          type: string
        in: query
        description: 'Sort records by the specified fields.


          The sort order for each sort field is ascending unless it is prefixed with a minus,

          in which case it is descending.


          Multiple sort fields supported by allowing comma-separated sort fields. Sort fields will be applied in the order specified.


          Sorting is allowed by the following fields: `id`, `created_at`.


          Example: `sort=id,-created_at`

          '
      responses:
        '200':
          $ref: '#/components/responses/ShipmentListResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Shipments
    post:
      summary: Create a Shipment
      operationId: createShipment
      requestBody:
        $ref: '#/components/requestBodies/CreateShipmentRequest'
      responses:
        '200':
          $ref: '#/components/responses/ShipmentResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Shipments
    servers:
    - url: https://app-sandbox.resolvepay.com/api
      description: Sandbox server
  /shipments/{shipment_id}:
    get:
      summary: Get a Shipment
      operationId: getShipment
      parameters:
      - name: shipment_id
        in: path
        schema:
          type: string
        required: true
        description: ID of the Shipment
        example: ship_1234567890abcdef
      responses:
        '200':
          $ref: '#/components/responses/ShipmentResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Shipments
    put:
      summary: Update a Shipment
      operationId: updateShipment
      parameters:
      - name: shipment_id
        in: path
        schema:
          type: string
        required: true
        description: ID of the Shipment to update
        example: ship_1234567890abcdef
      requestBody:
        $ref: '#/components/requestBodies/UpdateShipmentRequest'
      responses:
        '200':
          $ref: '#/components/responses/ShipmentResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Shipments
    delete:
      summary: Delete a Shipment
      operationId: deleteShipment
      parameters:
      - name: shipment_id
        in: path
        schema:
          type: string
        required: true
        description: ID of the Shipment to delete
        example: ship_1234567890abcdef
      responses:
        '200':
          $ref: '#/components/responses/ShipmentResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Shipments
    servers:
    - url: https://app-sandbox.resolvepay.com/api
      description: Sandbox server
  /shipments/{shipment_id}/sync:
    post:
      summary: Sync Shipment Tracking
      description: Synchronizes shipment tracking information by fetching real-time data from the courier using the existing tracking number. This endpoint retrieves the latest tracking updates directly from the shipping provider and performs instant verification of the shipment status, ensuring that the shipment data is current and accurate.
      operationId: syncShipmentTracking
      parameters:
      - name: shipment_id
        in: path
        schema:
          type: string
        required: true
        description: ID of the Shipment to sync tracking for
        example: ship_1234567890abcdef
      responses:
        '200':
          $ref: '#/components/responses/ShipmentResponse'
        '400':
          $ref: '#/components/responses/InvalidRequestOrValidationResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/RateLimitResponse'
      tags:
      - Shipments
    servers:
    - url: https://app-sandbox.resolvepay.com/api
      description: Sandbox server
components:
  responses:
    UnauthorizedResponse:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    InvalidRequestOrValidationResponse:
      description: Bad request error
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/ValidationError'
            - $ref: '#/components/schemas/InvalidRequestError'
    NotFoundResponse:
      description: Not found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    ShipmentResponse:
      description: An object representing the Shipment.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ShipmentObject'
    ShipmentListResponse:
      description: An object with an array of Shipments up to the specified limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ShipmentsList'
    RateLimitResponse:
      description: Rate limit error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
  schemas:
    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
    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
    ShipmentCreateRequest:
      type: object
      required:
      - merchant_invoice_id
      properties:
        merchant_invoice_id:
          type: string
          description: ID of the merchant invoice this shipment belongs to.
          example: inv_1234567890abcdef
        fulfillment_method:
          type: string
          description: 'Method of fulfillment for the shipment. Determines what additional fields are required:

            - `shipping_provider`: Requires `shipment_tracking_number` and `shipment_courier`. File is not allowed.

            - `self_delivery`, `customer_pickup`, `services_only`: Require a `file`. Tracking number and courier are optional.

            '
          enum:
          - shipping_provider
          - self_delivery
          - customer_pickup
          - services_only
          default: shipping_provider
          example: shipping_provider
        shipment_tracking_number:
          type: string
          description: Tracking number (required when fulfillment_method is shipping_provider, optional otherwise).
          example: 1Z123E45678901234
        shipment_courier:
          type: string
          description: 'Shipping courier (required when fulfillment_method is shipping_provider, optional otherwise). While any value can be accepted, instant verification is supported for specific couriers.


            See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.

            '
          example: ups
        file:
          $ref: '#/components/schemas/ShipmentFile'
          description: 'Proof of delivery file. Required for `self_delivery`, `customer_pickup`, and `services_only` fulfillment methods.

            Forbidden for `shipping_provider` fulfillment method.


            Use the `/shipments/sign-upload` endpoint to obtain a signed URL for uploading the file to S3, then include the uploaded file details here.

            '
          example:
            url: https://bucket.s3.amazonaws.com/1234567890-document.pdf
            size: 204800
            metadata:
              original_filename: proof_of_delivery.pdf
    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
    ShipmentsList:
      type: object
      properties:
        limit:
          type: integer
          description: Number of results returned per page.
          example: 10
        page:
          type: integer
          description: Current page number.
          example: 1
        count:
          type: integer
          description: Total number of shipments matching the query.
          example: 25
        results:
          type: array
          items:
            $ref: '#/components/schemas/ShipmentObject'
    ShipmentObject:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the Shipment.
          example: ship_1234567890abcdef
        merchant_invoice_id:
          type: string
          description: ID of the associated merchant invoice.
          example: inv_1234567890abcdef
        fulfillment_method:
          type: string
          description: Method of fulfillment for the shipment.
          enum:
          - shipping_provider
          - self_delivery
          - customer_pickup
          - services_only
          example: shipping_provider
        shipment_tracking_number:
          type: string
          description: Tracking number provided by the shipping courier.
          example: 1Z123E45678901234
        shipment_courier:
          type: string
          description: 'Shipping courier or provider name. While any value can be accepted, instant verification is supported for specific couriers.


            See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.

            '
          example: ups
        verification_status:
          type: string
          description: Manual or automatic verification status of the shipment.
          enum:
          - verified
          - pending
          example: verified
        created_at:
          type: string
          format: date-time
          description: Date time when the shipment was created.
          example: '2024-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          description: Date time when the shipment was last updated.
          example: '2024-01-15T14:45:00Z'
        tracking_status:
          type:
          - string
          - 'null'
          description: Current tracking status of the shipment from the courier.
          example: delivered
        tracking_substatus:
          type:
          - string
          - 'null'
          description: Detailed tracking substatus providing additional context about the shipment's current state.
          example: delivered_001
        expected_delivery:
          type:
          - string
          - 'null'
          format: date-time
          description: Expected delivery date and time provided by the shipping courier.
          example: '2024-01-20T18:00:00Z'
    ShipmentUpdateRequest:
      type: object
      properties:
        merchant_invoice_id:
          type: string
          description: ID of the merchant invoice (must belong to the authenticated merchant).
          example: inv_9876543210fedcba
        shipment_tracking_number:
          type: string
          description: Tracking number for the shipment.
          example: 1Z987F65432109876
        shipment_courier:
          type: string
          description: 'Shipping courier or provider name. While any value can be accepted, instant verification is supported for specific couriers.


            See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.

            '
          example: fedex
        file:
          $ref: '#/components/schemas/ShipmentFile'
          description: 'Proof of delivery file. Cannot be added for shipments with `shipping_provider` fulfillment method.


            Use the `/shipments/sign-upload` endpoint to obtain a signed URL for uploading the file to S3, then include the uploaded file details here.

            '
          example:
            url: https://bucket.s3.amazonaws.com/1234567890-document.pdf
            size: 204800
            metadata:
              original_filename: proof_of_delivery.pdf
    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
    ShipmentFile:
      type: object
      required:
      - url
      - size
      properties:
        url:
          type: string
          format: uri
          description: S3 URL of the uploaded file obtained after uploading to the signed URL from `/shipments/sign-upload`.
          example: https://bucket.s3.amazonaws.com/1234567890-document.pdf
        size:
          type: integer
          description: File size in bytes.
          example: 204800
        metadata:
          type: object
          description: Optional metadata about the file.
          properties:
            original_filename:
              type: string
              description: Original filename before upload.
              example: proof_of_delivery.pdf
          example:
            original_filename: proof_of_delivery.pdf
    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
    ShipmentCreateRequest_2:
      type: object
      required:
      - merchant_invoice_id
      properties:
        merchant_invoice_id:
          type: string
          description: ID of the invoice this shipment belongs to. The invoice must belong to one of your sub-merchants.
          example: inv_1234567890abcdef
        fulfillment_method:
          type: string
          description: 'Method of fulfillment for the shipment. Determines what additional fields are required:

            - `shipping_provider`: Requires `shipment_tracking_number` and `shipment_courier`. File is not allowed.

            - `self_delivery`, `customer_pickup`, `services_only`: Require a `file`. Tracking number and courier are optional.

            '
          enum:
          - shipping_provider
          - self_delivery
          - customer_pickup
          - services_only
          default: shipping_provider
          example: shipping_provider
        shipment_tracking_number:
          type: string
          description: Tracking number (required when fulfillment_method is shipping_provider, optional otherwise).
          example: 1Z123E45678901234
        shipment_courier:
          type: string
          description: 'Shipping courier (required when fulfillment_method is shipping_provider, optional otherwise). While any value can be accepted, instant verification is supported for specific couriers.


            See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.

            '
          example: ups
        file:
          $ref: '#/components/schemas/ShipmentFile'
          description: 'Proof of delivery file. Required for `self_delivery`, `customer_pickup`, and `services_only` fulfillment methods.

            Forbidden for `shipping_provider` fulfillment method.


            Use the `/shipments/sign-upload` endpoint to obtain a signed URL for uploading the file to S3, then include the uploaded file details here.

            '
          example:
            url: https://bucket.s3.amazonaws.com/1234567890-document.pdf
            size: 204800
            metadata:
              original_filename: proof_of_delivery.pdf
    ShipmentUpdateRequest_2:
      type: object
      properties:
        merchant_invoice_id:
          type: string
          description: ID of the invoice (must belong to one of your sub-merchants).
          example: inv_9876543210fedcba
        shipment_tracking_number:
          type: string
          description: Tracking number for the shipment.
          example: 1Z987F65432109876
        shipment_courier:
          type: string
          description: 'Shipping courier or provider name. While any value can be accepted, instant verification is supported for specific couriers.


            See the [Shipments API documentation](#tag/Shipments) for the complete list of supported couriers.

            '
          example: fedex
        file:
          $ref: '#/components/schemas/ShipmentFile'
          description: 'Proof of delivery file. Cannot be added for shipments with `shipping_provider` fulfillment method.


            Use the `/shipments/sign-upload` endpoint to obtain a signed URL for uploading the file to S3, then include the uploaded file details here.

            '
          example:
            url: https://bucket.s3.amazonaws.com/1234567890-document.pdf
            size: 204800
            metadata:
              original_filename: proof_of_delivery.pdf
  requestBodies:
    CreateShipmentRequest:
      description: Request body for creating a new shipment.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ShipmentCreateRequest'
    UpdateShipmentRequest:
      description: Request body for updating an existing shipment.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ShipmentUpdateRequest'
  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
x-refined-from:
- resolve-merchant-api-openapi.yaml
- resolve-partners-api-openapi.yaml