Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: ShopBase Internal Draft 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
servers:
- url: https://shop-name.onshopbase.com
tags:
- name: DraftOrder
paths:
/admin/draft_orders.json:
get:
summary: Retrieves a list of draft orders
description: Retrieves a list of draft orders.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DraftOrdersSwaggerResponse'
parameters:
- name: fields
description: A comma-separated list of fields to include in the response
in: path
required: true
schema:
type: string
- name: limit
description: 'Amount of results (default: 50, maximum: 250)'
in: path
required: true
schema:
type: number
- name: since_id
description: Restrict results to after the specified ID
in: path
required: true
schema:
type: number
- name: updated_at_min
description: Show orders last updated after date
in: path
required: true
schema:
type: string
- name: updated_at_max
description: Show orders last updated before date
in: path
required: true
schema:
type: string
- name: ids
description: Filter by list of IDs
in: path
required: true
schema:
type: number
- name: status
description: '**open**: All open orders (default) <br> **invoice_sent**: Show only closed orders <br> **completed**: Show only cancelled orders'
in: path
required: true
schema:
type: string
tags:
- DraftOrder
operationId: retrieves-a-list-of-draft-orders
security:
- APP_ACCESS_TOKEN: []
post:
summary: Creates a draft order.
description: 'Creates a draft order. Using the DraftOrder resource you can create orders in draft state using product variant line items, or custom line items. To create a product variant draft order, provide the `variant_id`, `quantity` and `discount` properties. To create a custom line item, provide the `title`, `price`, `taxable`, and `quantity` properties.
<code> > If you are using this endpoint with a Partner development store or a trial store, then you can only create five draft orders per minute.</code>
### About custom shipping lines
You can use the DraftOrder resource to send orders with custom shipping lines. A custom shipping line includes a title and price with handle set to Nil. A shipping line with a carrier provided shipping rate (currently set via the ShopBase admin) includes the shipping rate handle.
### Applying discounts
A draft order and its line items can have one discount each. Calculations for discounts are based on the setting of the value_type property, which can be set to either fixed_amount or percentage. For example, you can apply a fixed amount discount to a draft order to reduce the price by the specified value property. When you use a percentage discount, the discount amount property is the price multiplied by the value property. For line item discounts, the value property is applied per individual unit of the item, based on the line item''s quantity.
**Calculating line item discount amounts**
For `fixed_amount` discounts, the total `amount` corresponds to the line item quantity times the value of the discount. For percentage discounts, the total amount corresponds to the following:
`amount` = `floor(price * quantity * value) / 100, where floor()` is the usual round down function.
For non-fractional currencies, this formula needs to use round() instead of floor(), and the division by 100 takes place inside the rounding, resulting in a non-fractional value. Otherwise, an error is returned.
`amount` = `round(price * quantity * value / 100)`
**Line item examples**
_Fixed amount discount_
For a $19.99 line item with quantity of 2 and with $5 dollars off, discount amount corresponds to $10 ($5 * 2):
`applied_discount` : `{ "value_type": "fixed_amount", "value": 5, "amount": 10}`
_Percentage discount_
For a $19.99 line item with quantity of 2 and with 15% off, discount amount corresponds to $5.99 (floor ($19.99 * 2 * 15) / 100):
`applied_discount`: `{ "value_type": "percentage", "value": 15, "amount": 5.99 }`
### Loading and removing customers
You can load a customer to a draft order by sending the `customer_id` as part of the draft order object. The recommended way to remove a customer from a draft order is to make a POST request with the Customer object set to null, without specifying an email, shipping address, or billing address. A customer may also be removed by setting `customer`, `email`, `shipping_address` and `billing_address` to `null`'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DraftOrderSwaggerResponse'
tags:
- DraftOrder
operationId: create-a-draft-order
security:
- APP_ACCESS_TOKEN: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDto'
description: Order input request
description: Order input request
required: true
/admin/draft_orders/{draft_order_id:(?:\\d+)}.json:
get:
summary: Retrieves a specific draft order
description: Retrieves a specific draft order.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SingleDraftOrderSwaggerResponse'
parameters:
- name: fields
description: A comma-separated list of fields to include in the response
in: path
required: true
schema:
type: string
tags:
- DraftOrder
operationId: receive-a-single-draftorder
security:
- APP_ACCESS_TOKEN: []
delete:
summary: Deletes a draft order
description: Deletes a draft order
responses:
'200':
description: ''
tags:
- DraftOrder
operationId: deletes-a-draft-order
security:
- APP_ACCESS_TOKEN: []
put:
summary: Updates a draft order
description: Updates a draft order
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DraftOrderSwaggerResponse'
tags:
- DraftOrder
operationId: update-a-draft-order
security:
- APP_ACCESS_TOKEN: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
description: Order input request
description: Order input request
required: true
components:
schemas:
DraftOrderSwaggerResponse:
properties:
draft_order:
$ref: '#/components/schemas/OrderDto'
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
DraftOrdersSwaggerResponse:
properties:
draft_orders:
items:
$ref: '#/components/schemas/OrderDto'
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
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
RefundLineItemDto:
properties:
discount_amount:
type: number
description: The discount of the refund line item.
example: 10.99
line_item:
$ref: '#/components/schemas/OrderLineItemDto'
line_item_id:
type: integer
description: The ID of the related line item in the order.
example: 128323456
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_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
FulfillmentDto:
properties:
claim_id:
type: integer
description: the claim id of fulfillment
created_at:
type: integer
description: The date and time when the fulfillment was created. The API returns this value in ISO 8601 format.
date_done:
type: integer
description: The date and time (ISO 8601 format) when the fulfillment was fulfilled.
detected_tracking_company:
type: string
description: Detected tracking company
first_tracking_step_at:
type: integer
description: The date and time when the first tracking step created
id:
type: integer
description: The ID for the fulfillment.
example: 255858046
last_crawled_at:
type: integer
description: The date and time when the fulfillment was last crawled
last_mile_tracking_company:
type: string
description: The tracking company when the package arrived at destination country
last_mile_tracking_number:
type: string
description: The tracking number of packages when arrived at destination country
last_tracking_step_at:
type: integer
description: The date and time when the last tracking step created
name:
type: string
description: 'The uniquely identifying fulfillment name, consisting of two parts separated by a `.`. The first part represents the order name and the second part represents the fulfillment number.
The fulfillment number automatically increments depending on how many fulfillments are in an order (e.g. #1001.1, #1001.2).'
example: '255858046'
notify_customer:
type: boolean
description: "Whether the customer should be notified. \n If set to true, then an email will be sent when the fulfillment is created or updated.\nFor orders that were initially created using the API, the default value is false.\nFor all other orders, the default value is true."
example: true
order_id:
type: integer
description: The unique numeric identifier for the order.
example: 450789469
send_delay_mail:
type: boolean
description: check send email delay shipping
service:
type: string
description: 'The uniquely identifying fulfillment name, consisting of two parts separated by a `.`. The first part represents the order name and the second part represents the fulfillment number.
The fulfillment number automatically increments depending on how many fulfillments are in an order (e.g. #1001.1, #1001.2).'
example: '255858046'
shipment_status:
type: string
description: 'The current shipment status of the fulfillment. Valid values
</br>**label_printed**: A label for the shipment was purchased and printed.
</br>**label_purchased**: A label for the shipment was purchased, but not printed.
</br>**attempted_delivery**: Delivery of the shipment was attempted, but unable to be completed.
</br>**ready_for_pickup**: The shipment is ready for pickup at a shipping depot.
</br>**confirmed**: The carrier is aware of the shipment, but hasn''t recei
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/beeketing/refs/heads/main/openapi/beeketing-draftorder-api-openapi.yml