Beeketing Refund API

openapi: 3.2.0
info:
  title: ShopBase Internal Refund API
  termsOfService: http://swagger.io/terms/
  version: 1.0.0
  contact:
    url: /
    email: support@shopbase.com
  license:
    name: ShopBase Dev 1.0
    url: https://www.shopbase.net
  x-logo:
    url: https://admin-cdn.shopbase.com/img/Compact.ac400184.svg
  description: There are two major parts to a refund:</br>- A record of money returned to the customer</br>- The line items included in the refund, along with restocking instructions</br></br>Before you create a refund, use the calculate endpoint to generate accurate refund transactions. Specify the line items that are being refunded, their quantity and restock instructions, and whether you're refunding shipping costs. You can then use the response in the body of the request to create the actual refund.</br></br>When you create a refund using the response from the calculate endpoint, you can set additional options, such as whether to notify the customer of the refund. You can refund less than the calculated amount for either shipping or the line items by setting a custom value for the amount property.</br></br>If a refund includes shipping costs, or if you choose to refund line items for less than their calculated amount, then an order adjustment is created automatically to account for the discrepancy in the store's financial reports.
servers:
- url: https://shop-name.onshopbase.com
tags:
- description: There are two major parts to a refund:</br>- A record of money returned to the customer</br>- The line items included in the refund, along with restocking instructions</br></br>Before you create a refund, use the calculate endpoint to generate accurate refund transactions. Specify the line items that are being refunded, their quantity and restock instructions, and whether you're refunding shipping costs. You can then use the response in the body of the request to create the actual refund.</br></br>When you create a refund using the response from the calculate endpoint, you can set additional options, such as whether to notify the customer of the refund. You can refund less than the calculated amount for either shipping or the line items by setting a custom value for the amount property.</br></br>If a refund includes shipping costs, or if you choose to refund line items for less than their calculated amount, then an order adjustment is created automatically to account for the discrepancy in the store's financial reports.
  name: Refund
paths:
  /admin/orders/{order_id:[0-9]+}/refunds.json:
    get:
      summary: Retrieves a list of refunds for an order.
      description: Retrieve all refunds from a specific order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievesListRefundsSwaggerResponse'
      tags:
      - Refund
      operationId: retrieves-a-list-of-refunds-for-an-order
      security:
      - APP_ACCESS_TOKEN:
        - read_orders
    post:
      summary: Creates a refund
      description: Creates a refund. Use the calculate endpoint to produce the transactions to submit.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundSwaggerResponse'
      tags:
      - Refund
      operationId: create-the-refund
      security:
      - APP_ACCESS_TOKEN:
        - write_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createRefundRequestBody'
              description: When you use this endpoint with a Partner development store or a trial store, you can create only five refunds per minute.
        description: When you use this endpoint with a Partner development store or a trial store, you can create only five refunds per minute.
        required: true
  /admin/orders/{order_id:[0-9]+}/refunds/calculate.json:
    post:
      summary: Calculate the refund
      description: Calculate the refund.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateRefundSwaggerResponse'
      tags:
      - Refund
      operationId: calculate-the-refund
      security:
      - APP_ACCESS_TOKEN:
        - read_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateRequestBody'
              description: 'Calculates refund transactions based on line items and shipping. When you want to create a refund, you should first use the calculate endpoint to generate accurate refund transactions. Specify the line items that are being refunded, their quantity and restock instructions, and whether you intend to refund shipping costs. If the restock instructions can''t be met—for example, because you try to return more items than have been fulfilled—then the endpoint returns modified restock instructions. You can then use the response in the body of the request to create the actual refund. The response includes a transactions object with '
        description: 'Calculates refund transactions based on line items and shipping. When you want to create a refund, you should first use the calculate endpoint to generate accurate refund transactions. Specify the line items that are being refunded, their quantity and restock instructions, and whether you intend to refund shipping costs. If the restock instructions can''t be met—for example, because you try to return more items than have been fulfilled—then the endpoint returns modified restock instructions. You can then use the response in the body of the request to create the actual refund. The response includes a transactions object with '
        required: true
  /admin/orders/{order_id:[0-9]+}/refunds/{refund_id:[0-9]+}.json:
    get:
      summary: Retrieve a specific refund
      description: Retrieve a specific refund
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievesRefundsSwaggerResponse'
      tags:
      - Refund
      operationId: retrieve-a-specific-refund
      security:
      - APP_ACCESS_TOKEN:
        - read_orders
components:
  schemas:
    Request:
      properties:
        currency:
          type: string
          description: The three-letter code ([ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217)) for the currency used for the refund.
          example: USD
        is_dont_withdraw_from_balance_of_seller:
          type: boolean
          description: Refund dont using balance's seller.
          example: true
        mark_as_refund:
          type: boolean
          description: Whether mark as refund or not.
        note:
          type: string
          description: An optional note attached to a refund.
          example: wrong size
        notify:
          type: boolean
          description: Whether to send a refund notification to the customer.
          example: true
        payment_fee:
          type: number
          description: payment fee amount
          example: 10
        payment_gateway_inactive:
          type: boolean
          description: Whether the payment gateway is inactive.
        refund_line_items:
          items:
            $ref: '#/components/schemas/RefundLineItem'
          type: array
          description: "A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:\n * **line_item_id**:  The ID of a line item to refund.\n * **quantity**: The quantity to refund.\n * **restock_type**: How this refund line item affects inventory levels. (**no_restock**, **cancel**, **return**).\n * **location_id**: The ID of the location where the items should be restocked. This is required when the value of restock_type is return or cancel. If the item is not already stocked at the location, then the item is connected to the location. An error is returned when the item is connected to a fulfillment service location and a different location is provided."
        restock:
          type: boolean
          description: Whether to add the line items back to the store inventory. Use restock_type for refund line items instead.
          example: true
        shipping:
          $ref: '#/components/schemas/Shipping'
          description: Specify how much shipping to refund.
        support_refund_via_api:
          type: boolean
          description: Whether the payment gateway support refunding via API.
        transactions:
          items:
            $ref: '#/components/schemas/Transactions'
          type: array
          description: A list of transactions to process as refunds.
      type: object
    ShippingLinesDto:
      properties:
        carrier_identifier:
          type: string
          description: A reference to the carrier service that provided the rate. Present when the rate was computed by a third-party carrier service.
          example: third_party_carrier_identifier
        code:
          type: string
          description: A reference to the combined shipping method.
          example: weight_based_47925+weight_based_47926+weight_based_47928
        discounted_price:
          type: number
          description: The price of the shipping method after discounts.
          example: 4
        fulfillment_service:
          type: string
          description: A reference to the fulfillment service that is being requested for the shipping method. Present if the shipping method requires processing by a third party fulfillment service; null otherwise.
          example: third_party_fulfillment_service_id
        price:
          type: number
          description: The price of this shipping method in the shop currency. Can't be negative. (sum of all shipping rates price)
          example: 4
        source:
          type: string
          description: The source of the shipping method.
          example: canada_post
        tax_lines:
          items:
            $ref: '#/components/schemas/TaxLineDto'
          type: array
          description: A list of tax line objects, each of which details a tax applicable to this shipping line.
        title:
          type: string
          description: The title of the shipping method.
          example: Small Packet International Air
      type: object
    CalculateRequest:
      properties:
        currency:
          type: string
          description: The three-letter code ([ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217)) for the currency used for the payment.
          example: USD
        refund_line_items:
          items:
            $ref: '#/components/schemas/RefundLineItem'
          type: array
          description: "A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:\n * **line_item_id**:  The ID of a line item to refund.\n * **quantity**: The quantity to refund.\n * **restock_type**: How this refund line item affects inventory levels. (**no_restock**, **cancel**, **return**).\n * **location_id**: The ID of the location where the items should be restocked. This is required when the value of restock_type is return or cancel. If the item is not already stocked at the location, then the item is connected to the location. An error is returned when the item is connected to a fulfillment service location and a different location is provided."
        shipping:
          $ref: '#/components/schemas/Shipping'
          description: Specify how much shipping to refund.
      type: object
    CalculateResponse:
      properties:
        currency:
          type: string
          description: The three-letter code ([ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217)) for the currency used for the refund.
          example: USD
        maximum_refundable:
          type: number
        payment_gateway_inactive:
          type: boolean
          description: Whether the payment gateway is inactive.
        refund_line_items:
          items:
            $ref: '#/components/schemas/CalculateLineItemResponse'
          type: array
          description: "A list of line item IDs, quantities to refund, and restock instructions. Each entry has the following properties:\n * **line_item_id**:  The ID of a line item to refund.\n * **quantity**: The quantity to refund.\n * **restock_type**: How this refund line item affects inventory levels. (**no_restock**, **cancel**, **return**).\n * **location_id**: The ID of the location where the items should be restocked. This is required when the value of restock_type is return or cancel. If the item is not already stocked at the location, then the item is connected to the location. An error is returned when the item is connected to a fulfillment service location and a different location is provided."
        shipping:
          $ref: '#/components/schemas/CalculateShippingResponse'
          description: Specify how much shipping to refund.
        support_refund_via_api:
          type: boolean
          description: Whether the payment gateway support refunding via API.
        transactions:
          items:
            $ref: '#/components/schemas/CalculateTransactionResponse'
          type: array
          description: A list of transactions to process as refunds.
      type: object
    CalculateLineItemResponse:
      properties:
        discount_amount:
          type: number
          description: The discount of the refund line item.
          example: 10.99
        discount_per_item:
          type: number
        discounted_price:
          type: number
        discounted_total_price:
          type: number
        line_item_id:
          type: integer
          description: The ID of the related line item in the order.
          example: 128323456
        price:
          type: number
        quantity:
          type: integer
          description: The quantity of the associated line item that was returned.
          example: 2
        restock_type:
          type: string
          description: 'How this refund line item affects inventory levels. Valid values

            </br>**no_restock**: Refunding these items won''t affect inventory. The number of fulfillable units for this line item will remain unchanged. For example, a refund payment can be issued but no items will be returned or made available for sale again.

            </br>**cancel**: The items have not yet been fulfilled. The canceled quantity will be added back to the available count. The number of fulfillable units for this line item will decrease.

            </br>**return**: The items were already delivered, and will be returned to the merchant. The returned quantity will be added back to the available count. The number of fulfillable units for this line item will remain unchanged.

            </br>**legacy_restock**: The deprecated `restock` property was used for this refund. These items were made available for sale again. This value is not accepted when creating new refunds.'
          example: return
        subtotal:
          type: number
          description: The subtotal of the refund line item.
          example: 10.99
        title:
          type: string
          description: The title of the refund line item.
          example: Title
        total_cart_discount_amount:
          type: number
        total_refund:
          type: number
          description: The total refund on the refund line item.
          example: 2.67
        total_tax:
          type: number
          description: The total tax on the refund line item.
          example: 2.67
        variant_title:
          type: string
          description: The variant title of the refund line item.
          example: Variant title
      type: object
    RefundSeller:
      properties:
        amount:
          type: number
        created_at:
          type: integer
        id:
          type: integer
        params:
          type: string
        reason:
          type: string
        sb_order_id:
          type: integer
        shop_id:
          type: integer
        updated_at:
          type: integer
      type: object
    RetrievesListRefundsSwaggerResponse:
      properties:
        refund_sellers:
          items:
            $ref: '#/components/schemas/RefundSeller'
          type: array
        refunds:
          items:
            $ref: '#/components/schemas/RefundDto'
          type: array
      type: object
    AdditionalInformation:
      properties:
        ASN:
          type: integer
          description: ASN
        IPS:
          type: string
          description: Internet Service Provider
          example: FPT
        city:
          type: string
          description: City
          example: Hanoi
        country:
          type: string
          description: Country
          example: example country
        hostname:
          type: string
          description: Host name
          example: example host name
        latitude:
          type: string
          description: Latitude
          example: '27.683528'
        longitude:
          type: string
          description: Longtitude
          example: '27.683528'
        organization:
          type: string
          description: Organization
          example: example organization
        region:
          type: string
          description: Region
          example: VN
        timezone:
          type: string
          description: Time zone
          example: '7'
      type: object
    OrderDto:
      properties:
        access_key:
          type: string
          description: Access key
          example: 68778783ad298f1c80c3bafcddeea02f
        additional_information:
          $ref: '#/components/schemas/AdditionalInformation'
        applied_discount:
          $ref: '#/components/schemas/AppliedDiscount'
          description: 'The discount applied to the line item or the draft order object. Each draft order object can have one applied_discount object and each draft order line item can have its own applied_discount. The object has the following properties

            </br>**title**: Title of the discount.

            </br>**description**: Reason for the discount.

            </br>**value**: The value of the discount. If the type of discount is `fixed_amount` , then it corresponds to a fixed dollar amount. If the type is `percentage`, then it corresponds to percentage.

            </br>**value_type**: The type of discount. Valid values: percentage, fixed_amount.

            </br>**amount**: The applied amount of the discount, based on the setting of `value_type`.'
        balance:
          type: number
          description: Order balance
          example: 10000
        billing_address:
          $ref: '#/components/schemas/CustomerAddressDetail'
          description: 'The mailing address associated with the payment method. This address is an optional field that won''t be available on orders that do not require a payment method. It has the following properties

            </br>**address1**: The street address of the billing address.

            </br>**address2**: An optional additional field for the street address of the billing address.

            </br>**city**: The city, town, or village of the billing address.

            </br>**company**:  The company of the person associated with the billing address.

            </br>**country**: The name of the country of the billing address.

            </br>**country_code**: The two-letter code (ISO 3166-1 format) for the country of the billing address.

            </br>**first_name**: The first name of the person associated with the payment method.

            </br>**last_name**: The last name of the person associated with the payment method.

            </br>**latitude**: The latitude of the billing address.

            </br>**longitude**: The longitude of the billing address.

            </br>**name**: The full name of the person associated with the payment method.

            </br>**phone**: The phone number at the billing address.

            </br>**province**: The name of the region (province, state, prefecture, …) of the billing address.

            </br>**province_code**: The two-letter abbreviation of the region of the billing address.

            </br>**zip**: The postal code (zip, postcode, Eircode, …) of the billing address.'
        buyer_accepts_marketing:
          type: boolean
          description: Whether the customer consented to receive email updates from the shop.
          example: false
        cancel_reason:
          type: string
          description: 'The reason why the order was canceled.

            </br>**customer**: The customer canceled the order.

            </br>**fraud**: The order was fraudulent.

            </br>**inventory**: Items in the order were not in inventory.

            </br>**declined**: The payment was declined.

            </br>**other**: A reason not in this list.'
          example: customer
        cancelled_at:
          type: string
          description: The date and time ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)) when the order was canceled.
          example: '2019-04-22T11:00:00-05:00'
        cart_token:
          type: string
          description: Cart token
          example: 68778783ad298f1c80c3bafcddeea02f
        chargeback_amount:
          type: number
          description: The amount of chargeback.
          example: 1000
        chargeback_deadline_at:
          type: string
          description: The date and time ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)) when the order's chargeback end.
          example: '2019-04-22T11:00:00-05:00'
        chargeback_dispute_id:
          type: string
          description: The id of dispute
        chargeback_status:
          type: string
          description: 'The order''s chargeback status. Valid values

            </br>**null**: The order does not have any disputes.

            </br>**open**: The order''s dispute is open.

            </br>**lost**: Merchant lost the chargeback.

            </br>**won**: Merchant won the chargeback.'
        checkout_token:
          type: string
          description: Checkout token, unsing for checkout action
          example: 68778783ad298f1c80c3bafcddeea02f
        client_details:
          $ref: '#/components/schemas/ClientDetailsDto'
          description: Information about the browser that the customer used when they placed their order
        closed_at:
          type: string
          description: The date and time ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)) when the order was closed.
          example: '2019-04-22T11:00:00-05:00'
        created_at:
          type: string
          description: The autogenerated date and time ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)) when the order was created in ShopBase. The value for this property cannot be changed.
          example: '2019-04-22T11:00:00-05:00'
        created_at_in_timezone:
          type: string
          description: The autogenerated date and time ([ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601)) when the order was created by timezone in ShopBase. The value for this property cannot be changed.
          example: '2019-04-22T11:00:00-05:00'
        currency:
          type: string
          description: The three-letter code ([ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217)) for the shop currency.
          example: USD
        customer_locale:
          type: string
          description: The two or three-letter language code, optionally followed by a region modifier.
          example: en-CA
        discount_applications:
          items:
            $ref: '#/components/schemas/OrderDiscountApplicationDto'
          type: array
          description: An ordered list of stacked discount applications.
        discount_code:
          items:
            $ref: '#/components/schemas/OrderDiscountCodeDto'
          type: array
          description: A list of discount codes to apply to the order.
        email:
          type: string
          description: The customer's email address.
          example: bob.norman@hostmail.com
        financial_status:
          type: string
          description: 'The status of payments associated with the order. Can only be set when the order is created. Valid values

            </br>**pending**: The payments are pending. Payment might fail in this state. Check again to confirm whether the payments have been paid successfully.

            </br>**authorized**: The payments have been authorized.

            </br>**partially_paid**: The order have been partially paid.

            </br>**paid**: The payments have been paid.

            </br>**partially_refunded**: The payments have been partially refunded.

            </br>**refunded**: The payments have been refunded.

            </br>**voided**: The payments have been voided.'
          example: pending
        fulfillment_status:
          type: string
          description: 'The order''s status in terms of fulfilled line items. Valid values

            </br>**fulfilled**: Every line item in the order has been fulfilled.

            </br>**null**: None of the line items in the order have been fulfilled.

            </br>**partial**: At least one line item in the order has been fulfilled.

            </br>**restocked**: Every line item in the order has been restocked and the order canceled.

            </br>**processing**: Every line item in the order is in processing. (except Printbase plan)

            </br>**processing**: Use Printbase plan - Order has been placed to supplier.

            </br>**partial-processing**: At least one line item in the order is in processing.'
        fulfillments:
          items:
            $ref: '#/components/schemas/FulfillmentDto'
          type: array
          description: List fulfillments
        id:
          type: integer
          description: Order ID
          example: 450789469
        is_in_post_purchase:
          type: boolean
          description: Whether in post purchase or not
          example: true
        is_risk:
          type: boolean
          description: Is order risk
        line_items:
          items:
            $ref: '#/components/schemas/OrderLineItemDto'
          type: array
          description: A list of line item objects, each containing information about an item in the order. Each object has the following properties
        name:
          type: string
          description: Order name
          example: example name
        not_explicit_discount:
          type: number
          description: Not explicit discount
          example: 123
        note:
          type: string
          description: An optional note that a shop owner can attach to the order.
          example: Customer changed their mind.
        note_attributes:
          items:
            type: '&{%!s(token.Pos=12336) string string}'
          type: array
          description: Extra information that is added to the order. Appears in the **Additional details** section of an order details page. Each array entry must contain a hash with `name` and `value` keys.
        order_number:
          type: integer
          description: The ID of the order used by the shop owner and customer. This is different from the `id` property, which is the ID of the order used by the API.
          example: 100
        order_status_url:
          type: string
          description: The URL pointing to the order status web page, if applicable.
          example: https://checkout.shopbase.com/112233/checkouts/4207896aad57dfb159/thank_you_token?key=753621327b9e8a64789651bf221dfe35
        original_total_price:
          type: number
          description: Original total price
          example: 10001203
        payment_gateway:
          type: string
          description: Payment gateway
          example: paypal
        payment_gateway_names:
          items:
            type: string
          type: array
          description: The list of payment gateways used for the order.
        phone:
          type: string
          description: The customer's phone number.
          example: '+557734881234'
        post_purchase_timeout_at:
          type: string
          description: Post purchase timeout at time
          example: '2019-04-22T11:00:00-05:00'
        previous_shipping_fee:
          type: number
          description: Previous shiping fee
          example: 10000
        processed_at:
          type: string
          description: Time this order be processed
          example: '2019-04-22T11:00:00-05:00'
        referring_site:
          type: string
          description: The website where the customer clicked a link to the shop.
          example: http://www.anexample.com
        refunds:
          items:
            $ref: '#/components/schemas/RefundDto'
          type: array
          description: A list of refunds applied to the order. For more information, see the Refund API.
        shipping_address:
          $ref: '#/components/schemas/CustomerAddressDetail'
          description: The mailing address to where the order will be shipped. This address is optional and will not be available on orders that do not require shipping.
        shipping_discount:
          type: number
          description: Caculated shipping discount
          example: 2
        shipping_fee:
          type: number
          description: Caculated shipping fee
          example: 10
        shipping_lines:
          items:
            $ref: '#/components/schemas/ShippingLinesDto'
          type: array
          description: An array of objects, each of which details a shipping method used
        shipping_tax:
          type: number
          description: Caculated shipping tax
          example: 2
        shop_id:
          type: integer
          description: Shop ID
          example: 123123
        source_name:
          type: string
          description: 'Where the order originated. Can be set only during order creation, and is not writeable afterwards. Values for ShopBase channels are protected and cannot be assigned by other API clients: web, pos, shopbase_draft_order, iphone, and android. Orders created via the API can be assigned any other string of your choice. If unspecified, then new orders are assigned the value of your app''s ID.'
          example: web
        subtotal_price:
          type: number
          description: Subtotal price
          example: 123
        tags:
          type: string
          description: Tags attached to the order, formatted as a string of comma-separated values. Tags are additional short descriptors, commonly used for filtering and searching. Each individual tag is limited to 40 characters in length.
        tax_lines:
          items:
            $ref: '#/components/schemas/TaxLineDto'
          type: array
          description: A list of tax line objects.
        taxes_included:
          type: boolean
          description: Whether taxes are included in the order subtotal.
          example: true
        token:
          type: string
          description: Checkout token, unsing for identifing
          example: 68778783ad298f1c80c3bafcddeea02f
        total_discounts:
          type: number
          description: Total discounts
          example: 1
        total_line_items_discount:
          type: number
          description: Total line item discount
          example: 123
        total_line_items_price:
          type: number
          description: Total line item price
          example: 123
        total_price:
          type: number
          description: Total price
          example: 100000
        total_quantity:
          type: number
          description: Total quantity
          example: 100
        total_shipping:
          type: number
          description: it's equal shipping_fee - shipping_discount + shipping_tax
          example: 10
        total_tax:
          type: number
          description: Total tax
          example: 123
        total_tip_received:
          type: number
          description: The sum of all the tips in the order in the shop currency.
          example: 4.87
        total_weight:
          type: number
          description: Total height
 

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/beeketing/refs/heads/main/openapi/beeketing-refund-api-openapi.yml