---
title: "Import Refund"
method: POST
path: "/refunds"
tags: ["Refunds"]
---

# Import Refund

`POST /refunds`

## Request

- Base URL: `https://api.upflow.io/v1`
- URL: `https://api.upflow.io/v1/refunds`
- Auth: API key in header `X-Api-Key` and API key in header `X-Api-Secret`

This endpoint can be used to create or update (if externalId already
exists) a refund.

It cannot be used when using a native integration as refunds are only
created by the native integration in that case.

## Request body

- RefundCreation: Common attributes for refunds.
  - `refNumber` string, required: Refund reference number.
  - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
  - `amount` integer, required: Refund amount (in cents).
  - `instrument` 'WIRE_TRANSFER' | 'DIRECT_DEBIT' | 'CARD' | 'CASH' | 'CHECK' | 'UNKNOWN': Instrument used for the payment.
  - `validatedAt` string, date-time, required: The date when the refund is validated (ISO 8601 format).
  - `externalId` string: Refund external identifier.
  - `linkedPayments` PaymentAllocationCreation[]: Payments to link to this refund.
    - `amountLinked` integer, required: Refund share to allocate to the payment (in cents).
    - `payment` union, required: Reference to a payment, identifiable by ID or external ID.
      - object
        - `id` string, uuid, required: The payment transaction ID.
        - `externalId` string: The payment external ID.
      - object
        - `id` string, uuid: The payment transaction ID.
        - `externalId` string, required: The payment external ID.
  - `linkedCreditNotes` CreditNoteAllocationCreation[]: Credit notes to link to this refund.
    - `amountLinked` integer, required: Refund share to allocate to the credit note (in cents).
    - `creditNote` union, required: Reference to a credit note, identifiable by ID, external ID, or custom ID.
      - object
        - `id` string, uuid, required: The credit note ID.
        - `externalId` string: The credit note external ID.
        - `customId` string: The credit note custom ID.
      - object
        - `id` string, uuid: The credit note ID.
        - `externalId` string, required: The credit note external ID.
        - `customId` string: The credit note custom ID.
      - object
        - `id` string, uuid: The credit note ID.
        - `externalId` string: The credit note external ID.
        - `customId` string, required: The credit note custom ID.
  - `customer` union: Reference to a customer, identifiable by ID or external ID.
    - object
      - `id` string, uuid, required: The Customer ID.
      - `externalId` string: An external ID that uniquely references the customer.
    - object
      - `id` string, uuid: The Customer ID.
      - `externalId` string, required: An external ID that uniquely references the customer.

## Response `200`

Refund Created or Updated (Note: Apiary doc says 200, usually POST for create returns 201. Sticking to doc.)

- Refund: Common attributes for refunds.
  - `refNumber` string, required: Refund reference number.
  - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
  - `amount` integer, required: Refund amount (in cents).
  - `instrument` 'WIRE_TRANSFER' | 'DIRECT_DEBIT' | 'CARD' | 'CASH' | 'CHECK' | 'UNKNOWN': Instrument used for the payment.
  - `validatedAt` string, date-time, required: The date when the refund is validated (ISO 8601 format).
  - `externalId` string: Refund external identifier.
  - `id` string, uuid, required: The Refund ID.
  - `amountLinked` integer, required: Amount linked to the refund (in cents).
  - `modifiedAt` string, date-time, required: The date when the refund was last updated (ISO 8601 format).
  - `linkedTransactions` PaymentAllocation[]: (Deprecated - likely replaced by linkedPayments) List of linked payments with the allocated amount.
    - `linkedAmount` integer, required: Refund's share linked to the payment (in cents).
    - `payment` PaymentCommonAttribs, required: Common attributes for payments.
      - `refNumber` string, required: Payment reference number.
      - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
      - `amount` integer, required: Payment amount (in cents).
      - `instrument` 'WIRE_TRANSFER' | 'DIRECT_DEBIT' | 'CARD' | 'CASH' | 'CHECK' | 'UNKNOWN': Instrument used for the payment.
      - `validatedAt` string, date-time, required: The date when the payment is validated (ISO 8601 format).
      - `externalId` string: Payment external identifier.
      - `customFields` CustomFieldValueAttribs[]: List of payment's custom fields values.
        - `id` string, uuid, nullable: The Custom Field ID.
        - `externalId` string, nullable: Custom field external identifier.
        - `value` union: The value of the custom field. Can be a primitive (string, integer, boolean), a single object for SELECT types, an array of objects for MULTI_SELECT types.
          - integer: Integer value.
          - string: String value (could also be date-time or date).
          - boolean: Boolean value.
          - CustomFieldValueOption
            - `externalId` string, nullable: External identifier for the option.
            - `label` string, required: Display label for the option.
          - CustomFieldValueOption[]: Value for MULTI_SELECT type.
            - `externalId` string, nullable: External identifier for the option.
            - `label` string, required: Display label for the option.
  - `linkedPayments` PaymentAllocation[]: List of payments linked to this refund.
    - `linkedAmount` integer, required: Refund's share linked to the payment (in cents).
    - `payment` PaymentCommonAttribs, required: Common attributes for payments.
      - `refNumber` string, required: Payment reference number.
      - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
      - `amount` integer, required: Payment amount (in cents).
      - `instrument` 'WIRE_TRANSFER' | 'DIRECT_DEBIT' | 'CARD' | 'CASH' | 'CHECK' | 'UNKNOWN': Instrument used for the payment.
      - `validatedAt` string, date-time, required: The date when the payment is validated (ISO 8601 format).
      - `externalId` string: Payment external identifier.
      - `customFields` CustomFieldValueAttribs[]: List of payment's custom fields values.
        - `id` string, uuid, nullable: The Custom Field ID.
        - `externalId` string, nullable: Custom field external identifier.
        - `value` union: The value of the custom field. Can be a primitive (string, integer, boolean), a single object for SELECT types, an array of objects for MULTI_SELECT types.
          - integer: Integer value.
          - string: String value (could also be date-time or date).
          - boolean: Boolean value.
          - CustomFieldValueOption
            - `externalId` string, nullable: External identifier for the option.
            - `label` string, required: Display label for the option.
          - CustomFieldValueOption[]: Value for MULTI_SELECT type.
            - `externalId` string, nullable: External identifier for the option.
            - `label` string, required: Display label for the option.
  - `linkedCreditNotes` CreditNoteAllocation[]: List of credit notes linked to this refund.
    - `linkedAmount` integer, required: Refund's share linked to the credit note (in cents).
    - `creditNote` CreditNoteCommonAttribs, required: Common attributes for credit notes.
      - `customId` string, required: Credit note custom identifier (e.g., document number).
      - `externalId` string: Credit note external identifier.
      - `issuedAt` string, date-time: The date at which the credit note was issued (ISO 8601 format).
      - `dueDate` string, date-time: The date when the credit note is due (ISO 8601 format). Often same as issuedAt.
      - `name` string: The credit note name or description.
      - `currency` 'EUR' | 'CHF' | 'USD' | 'CAD' | 'GBP', required: ISO 4217 Currency Code
      - `grossAmount` integer, required: Amount including taxes (in cents).
      - `netAmount` integer, required: Amount net of taxes (in cents).
      - `updatedAt` string, date-time: The date at which the credit note was last updated (ISO 8601 format).
  - `customer` CustomerLite: Minimal customer information.
    - `id` string, uuid, required: The Customer ID.
    - `externalId` string: An external ID that uniquely references the customer.
    - `companyName` string, required: Customer name.
    - `accountingRef` string: (Deprecated) Customer accounting reference (used in accounting tool). Use a custom field instead.
  - `createdAt` string, date-time: The date at which the refund was created (ISO 8601 format).
  - `updatedAt` string, date-time: The date at which the refund was last updated (ISO 8601 format).

---

[API](https://skmtc.dev/upflow/apis/upflow-api.md) - [All operations](https://skmtc.dev/upflow/apis/upflow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/upflow/apis/upflow-api/revisions/898a98ca0587?raw)