Beeketing Order API

openapi: 3.2.0
info:
  title: ShopBase Internal Order 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: An order is a customer's completed request to purchase one or more products from a shop. An order is created when a customer completes the checkout process, during which time they provide an email address or phone number, billing address and payment information. </br></br>Orders can be created through the API, but no payment information will be collected, and no transaction performed. You can mark the order with any payment status
servers:
- url: https://shop-name.onshopbase.com
tags:
- description: An order is a customer's completed request to purchase one or more products from a shop. An order is created when a customer completes the checkout process, during which time they provide an email address or phone number, billing address and payment information. </br></br>Orders can be created through the API, but no payment information will be collected, and no transaction performed. You can mark the order with any payment status
  name: Order
paths:
  /admin/orders.json:
    get:
      summary: Retrieves a list of orders
      description: Retrieve all orders
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersSwaggerResponse'
      tags:
      - Order
      operationId: retrieves-a-list-of-orders
      security:
      - APP_ACCESS_TOKEN:
        - read_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrdersSwaggerRequest'
              description: Orders request
        description: Orders request
        required: true
    post:
      summary: Creates an order
      description: Creates an order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSwaggerResponse'
      tags:
      - Order
      operationId: creates-an-order
      security:
      - APP_ACCESS_TOKEN:
        - write_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderDto'
              description: Order DTO
        description: Order DTO
        required: true
  /admin/orders/count.json:
    get:
      summary: Retrieves an order count
      description: Retrieves an order count
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'
      tags:
      - Order
      operationId: retrieves-an-order-count
      security:
      - APP_ACCESS_TOKEN:
        - read_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrdersSwaggerRequest'
              description: Order request
        description: Order request
        required: true
  /admin/orders/{order_id:(?:\\d+)}.json:
    get:
      summary: Retrieve a single order
      description: Retrieves a specific order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSwaggerResponse'
      tags:
      - Order
      operationId: retrieves-a-specific-order
      security:
      - APP_ACCESS_TOKEN:
        - read_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
              description: Order Request
        description: Order Request
        required: true
    delete:
      summary: Deletes an order
      description: Deletes an order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/models.SwaggerDeleteResponse'
      parameters:
      - name: order_id
        description: Order ID
        in: path
        required: true
        schema:
          type: number
      tags:
      - Order
      operationId: deletes-an-order
      security:
      - APP_ACCESS_TOKEN:
        - write_orders
    put:
      summary: Updates an order
      description: Updates an order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSwaggerResponse'
      parameters:
      - name: order_id
        description: Order ID
        in: path
        required: true
        schema:
          type: integer
      tags:
      - Order
      operationId: updates-an-order
      security:
      - APP_ACCESS_TOKEN:
        - write_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
              description: Order Request
        description: Order Request
        required: true
  /admin/orders/{order_id:[0-9]+}/adjust.json:
    put:
      summary: Adjust quantity or add new custom line item to order.
      description: Adjust quantity or add new custom line item to order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSwaggerResponse'
      tags:
      - Order
      operationId: adjust-order
      security:
      - APP_ACCESS_TOKEN:
        - write_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustOrderDto'
              description: Order Adjust Request
        description: Order Adjust Request
        required: true
  /admin/orders/{order_id:[0-9]+}/cancel.json:
    post:
      summary: Cancel an order
      description: Cancel and refund a specific order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSwaggerResponse'
      parameters:
      - name: order_id
        description: Order ID
        in: path
        required: true
        schema:
          type: integer
      tags:
      - Order
      operationId: cancel-specific-order
      security:
      - APP_ACCESS_TOKEN:
        - write_orders
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/cancelOrderData'
              description: Using an `empty object` to fully cancel and refund an order. To cancel and refund a specific amount of money, use `amount` property. The `refund` property is used to cancel and refund a specific amount of each line items.
        description: Using an `empty object` to fully cancel and refund an order. To cancel and refund a specific amount of money, use `amount` property. The `refund` property is used to cancel and refund a specific amount of each line items.
        required: true
  /admin/orders/{order_id:[0-9]+}/open.json:
    post:
      summary: Open-Close a closed order
      description: Open-Close a closed order
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderSwaggerResponse'
      parameters:
      - name: order_id
        description: Order ID
        in: path
        required: true
        schema:
          type: string
      tags:
      - Order
      operationId: open-specific-order
      security:
      - APP_ACCESS_TOKEN:
        - write_orders
components:
  schemas:
    OrdersSwaggerResponse:
      properties:
        orders:
          items:
            $ref: '#/components/schemas/OrderDto'
          type: array
      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
    AdjustLineItemDto:
      properties:
        id:
          type: integer
        is_custom:
          type: boolean
        name:
          type: string
        price:
          type: number
        properties:
          type: string
        quantity:
          type: number
        require_shipping:
          type: boolean
        restock:
          type: boolean
        variant_id:
          type: integer
      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
          example: 10
        updated_at:
          type: string
          description: Time auto generate when the order was updated
          example: '2019-04-22T11:00:00-05:00'
        weight_unit:
          type: string
          description: weight_unit
          example: Kg
      type: object
    TaxLineDto:
      properties:
        price:
          type: number
          description: The amount added to the order for this tax in the shop currency.
          example: 25.81
        rate:
          type: number
          description: The tax rate applied to the order to calculate the tax price.
          example: 0.13
        title:
          type: string
          description: The name of the tax.
          example: HST
      type: object
    OrderDiscountCodeDto:
      properties:
        amount:
          type: number
          description: The value of the discount to be deducted from the order total. The type field determines how this value is calculated. After an order is created, this field returns the calculated amount.
          example: 30
        code:
          type: string
          description: The discount code.
          example: SPRING30
        discount_type:
          type: string
          description: Discount type
        price_rule_id:
          type: integer
          description: Price rule id
        price_rule_type:
          type: string
          description: Price rule type
        scope:
          type: string
        type:
          type: string
          description: 'The type of discount. Default value: `fixed_amount`'
          example: fixed_amount
      type: object
    models.SwaggerDeleteResponse:
      type: object
    OrdersSwaggerRequest:
      properties:
        chargeback_deadline_at_max:
          type: string
          description: 'Show orders chargeback deadline at or before date. (format: 2014-04-25T16:15:47-04:00)'
          example: '2014-04-25T16:15:47-04:00'
        chargeback_deadline_at_min:
          type: string
          description: 'Show orders chargeback deadline at or after date. (format: 2014-04-25T16:15:47-04:00)'
          example: '2014-04-25T16:15:47-04:00'
        chargeback_status:
          type: string
          description: 'Filter orders by their chargeback status, specified by a comma-separated list of statuses.

            </br>Acceptable value: **open**, **submitted**, **won**, **lost**.'
          example: submitted
        created_at_max:
          type: string
          description: 'Show orders created at or before date. (format: 2014-04-25T16:15:47-04:00)'
          example: '2014-04-25T16:15:47-04:00'
        created_at_min:
          type: string
          description: 'Show orders created at or after date. (format: 2014-04-25T16:15:47-04:00)'
          example: '2014-04-25T16:15:47-04:00'
        customer_email:
          type: string
          description: Filter orders by their customer email.
          example: example@shopbase.com
        customer_id:
          type: integer
          description: ID of customer
          example: 1234567
        fields:
          type: string
          description: Retrieve only certain fields, specified by a comma-separated list of fields names.
          example: id
        filter_order_risk:
          type: boolean
          description: Filter orders by risk level.
          example: false
        financial_status:
          type: string
          description: 'Filter orders by their financial status, specified by a comma-separated list of statuses.

            </br>**authorized**: Show only authorized orders.

            </br>**pending**:  Show only pending orders.

            </br>**paid**: Show only paid orders.

            </br>**partially_paid**: Show only partially paid orders.

            </br>**refunded**: Show only refunded orders.

            </br>**partially_refunded**: Show only partially refunded orders.

            </br>**unpaid**: Show authorized and partially paid orders.

            </br>**voided**: Show only voided orders.

            </br>**any**: Show orders of any financial status.'
          example: authorized,pending
        fulfilled_at_max:
          type: string
          description: 'Show orders fulfilled at or before date. (format: 2014-04-25T16:15:47-04:00)'
          example: '2014-04-25T16:15:47-04:00'
        fulfilled_at_min:
          type: string
          description: 'Show orders fulfilled at or after date. (format: 2014-04-25T16:15:47-04:00)'
          example: '2014-04-25T16:15:47-04:00'
        fulfillment_service:
          type: string
          description: Filter orders by their fulfillment service handle, specified by a comma-separated list of services.
        fulfillment_status:
          type: string
          description: 'Filter orders by their fulfillment status, specified by a comma-separated list of statuses.

            </br>**fulfilled**: Show orders that have been shipped (alias: **shipped**).

            </br>**partial**:  Show partially shipped orders.

            </br>**unfulfilled**: Show orders that have not yet fulfilled or partial (alias: **unshipped**).

            </br>**any**: Show orders of any fulfillment status.

            </br>**restocked**: Show order that have been restocked.

            </br>**processing**: Show order that in processing.

            </br>**partial-processing**: Show partially processing orders.'
          example: fulfilled
        ids:
          items:
            type: integer
          type: array
          description: List of order ID
          example:
          - 23556
          - 12345
        limit:
          type: integer
          description: 'The maximum number of results to show on a page. (default: 50, maximum: 250)'
          example: 50
        not_product_mapping:
          type: boolean
          description: Filter order by line item's product not mapped.
          example: false
        not_product_name:
          type: string
          description: Filter orders by line item's product name which not contains.
          example: jean
        not_product_sku:
          type: string
          description: Filter orders by line item's product sku which not contains.
          example: esku-1234566
        not_product_type:
          type: string
          description: Filter orders by line item's product type which not contains.
          example: cute
        not_product_vendor:
          type: strin

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