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

# Create an idempotent settlement order

> Reserves an unexpired quote for this organization. Creating the order
does not move funds. The response contains the Arc approval and CCTP
burn calls for the user wallet. The organization must have an active,
funded Arbitrum settlement account.




## OpenAPI

````yaml /openapi.yaml post /api/integrations/settlements/orders
openapi: 3.1.0
info:
  title: COP By Integrations API
  version: 0.1.0
  description: |
    Non-custodial Celo API for partners. Prepare swaps and BRE-B COP payouts;
    the user signs from their wallet. Confirm with the transaction hash.
servers:
  - url: https://api.copby.digitalcop.shop
    description: Production API
security:
  - bearerAuth: []
tags:
  - name: Settlement
    description: Quote Arc USDC and create settlement orders that deliver COPm on Celo
  - name: Swaps
    description: Prepare and confirm onchain COPm swaps
  - name: BRE-B
    description: Quote, KYC, and COP payouts via Bridge Bre-B
  - name: Webhooks
    description: >
      Bridge → COP By inbound callbacks, plus outbound partner payout webhooks
      (REQ-INT-WH-01).

      Partners configure URL + signing secret in the dashboard; deliveries are
      HMAC-signed.
paths:
  /api/integrations/settlements/orders:
    post:
      tags:
        - Settlement
      summary: Create an idempotent settlement order
      description: |
        Reserves an unexpired quote for this organization. Creating the order
        does not move funds. The response contains the Arc approval and CCTP
        burn calls for the user wallet. The organization must have an active,
        funded Arbitrum settlement account.
      operationId: createSettlementOrder
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            maxLength: 200
          description: Unique key for one logical order
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSettlementOrderRequest'
            example:
              quoteId: qst_example
              reference: customer-deposit-1042
      responses:
        '201':
          description: Settlement order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementOrderCreated'
        '400':
          $ref: '#/components/responses/SettlementError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/SettlementError'
        '409':
          $ref: '#/components/responses/SettlementError'
        '429':
          $ref: '#/components/responses/SettlementError'
components:
  schemas:
    CreateSettlementOrderRequest:
      type: object
      required:
        - quoteId
      properties:
        quoteId:
          type: string
          maxLength: 40
        reference:
          type: string
          maxLength: 200
    SettlementOrderCreated:
      type: object
      required:
        - orderId
        - status
        - health
        - fundsStatus
        - execution
      properties:
        orderId:
          type: string
          example: ord_example
        status:
          type: string
          enum:
            - CREATED
        health:
          type: string
          enum:
            - HEALTHY
        fundsStatus:
          type: string
          enum:
            - IN_USER_WALLET
        execution:
          type: object
          required:
            - chainId
            - atomicBatch
            - sequential
          properties:
            chainId:
              type: integer
              enum:
                - 5042
            atomicBatch:
              $ref: '#/components/schemas/ArcExecutionPlan'
            sequential:
              $ref: '#/components/schemas/ArcExecutionPlan'
    ArcExecutionPlan:
      type: object
      required:
        - calls
        - estimatedUserConfirmations
        - mode
      properties:
        calls:
          type: array
          minItems: 1
          maxItems: 2
          items:
            type: object
            required:
              - to
              - data
              - value
            properties:
              to:
                $ref: '#/components/schemas/Address'
              data:
                type: string
                description: Encoded contract calldata
              value:
                type: string
                enum:
                  - '0'
        estimatedUserConfirmations:
          type: integer
          minimum: 1
          maximum: 2
        mode:
          type: string
          enum:
            - atomic_batch
            - sequential
            - burn_only
    SettlementErrorBody:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - stage
            - fundsStatus
            - fundsMoved
            - retryable
            - nextAction
          properties:
            code:
              type: string
              enum:
                - INVALID_REQUEST
                - RATE_LIMITED
                - INVALID_AMOUNT
                - INVALID_SOURCE_ADDRESS
                - INVALID_DESTINATION_ADDRESS
                - BELOW_MINIMUM
                - ABOVE_MAXIMUM
                - QUOTE_EXPIRED
                - QUOTE_NOT_FOUND
                - ROUTE_UNAVAILABLE
                - SLIPPAGE_LIMIT_EXCEEDED
                - MENTO_CAPACITY_EXCEEDED
                - IDEMPOTENCY_CONFLICT
                - QUOTE_ALREADY_USED
                - INVALID_BURN
                - BURN_ALREADY_USED
                - INVALID_IDEMPOTENCY_KEY
                - ORDER_NOT_FOUND
                - PROVIDER_UNAVAILABLE
                - INTERNAL_ERROR
                - INTAKE_PAUSED
                - SETTLEMENT_ACCOUNT_INACTIVE
            message:
              type: string
            stage:
              type: string
            fundsStatus:
              type: string
            fundsMoved:
              type: boolean
            retryable:
              type: boolean
            nextAction:
              type: string
            requestId:
              type: string
    Address:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      example: '0x2222222222222222222222222222222222222222'
  responses:
    SettlementError:
      description: Settlement lifecycle error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SettlementErrorBody'
    Unauthorized:
      description: Missing or invalid integration API key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Integration API key. Send as `Bearer copby_live_pk_…`.

````

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