MENU

Baskets/Orders

Description

Use our /order endpoint to get, update and create new details of your basket aka orders, basket items. This method will fetch and update the basket regardless of it's status. The output will be returned in JSON Format.

Endpoint

https://api.website.world/webapps/api/order

https://api.website.world/webapps/api/basket   (Alias, same endpoint)

Filter Parameters

Used to filter a list of orders/baskets returned, except id which returns a singular.

NameDescriptionExampleData type
b_cust_name 

Filter results based on customer name

b_cust_name=John

string
mbr_id 

Filter results based on member id

mbr_id=123 int
id 

Get a single order/basket (singular data object)

b_id=123

int
invoice_id

Filter results based on the final invoice id reference... usually the same as b_id, but can have prefixes and a different number sequence.   aka b_invoice_id

invoice_id=INV003

text
readyToShip 

Filter results based on orders that are paid and ready to be shipped

readyToShip=1

int
isPaid

Filter results based on orders that are paid isPaid=1, or unpaid isPaid=0

isPaid=1

bool
isShipped Filter results based on orders that are shipped isShipped=1, or unshipped  if isShipped=0 isShipped=1
bool
isCancelled Filter results based on orders that are cancelled, by default cancelled orders are excluded isCancelled=1
bool
orderedAfter

Get orders placed after timestamp

orderedAfter=2020-02-28 12:00:00

string
orderedBefore

Get orders placed before timestamp

orderedBefore=2020-03-01 18:00:00

string
paidAfter Get orders paid after timestamp paidAfter=2020-02-28 12:00:00 string
paidBefore Get orders paid before timestamp paidBefore=2020-03-01 18:00:00
orderBy

Sort results based on date created, order date, payment date, shippped date

orderby=created

orderby=order_date

orderby=paid_date

orderby=shipped_date

string
orderDirection Sort results in ascending or descending order

orderDirection=reverse 

string
includeBasketItems Include basket items in the response for GET list... included by default for single object fetches, excluded by default on multiple object searches.

includeBasketItems=1

int/string

Action Parameters

The following parameters should be used for advanced processing of the data, and is usually focused on a "single order" GET or POST

NameDescriptionExampleData type
doAction=CalculateTotals ACTION: Calculate and update the total of the basket, 
Do not include this parameter if do not wish to calculate totals.
doAction=CalculateTotals string
doAction=UpdateShippingStatus ACTION : Updates shipping status to shipped, updates shipping dates... 
You should set the other fields using json data, eg b_courier_ref, b_courier_url, b_courier_notes

doAction=UpdateShippingStatus

string
doNotSendNotification Optionally provide doNotSendNotification=1 if you want to prevent the default sending of the branded shipping notification to the customer

doNotSendNotification=1

int
ReduceStock

ACTION: Calculate and update the stock of the product when new order is created.

NOTE: The default logic assumes basket data is being added/updated, but not closed.

The above action should only be triggered ONCE per order.

doAction=ReduceStock

string
doAction=ProcessOnPaidActions ACTION: Trigger On Paid Actions.  doAction=ProcessOnPaidActions string
doAction=ProcessPoints ACTION: Trigger Member Points processing. doAction=ProcessPoints string
doAction=SendInvoice ACTION: Send Invoices to Customer email. doAction=SendInvoice string
doAction=SendOrder ACTION: Send Order to Customer email. doAction=SendOrder string
doAction=SendMerchantOrder ACTION: Send Merchant Order Copy to Customer email. doAction=SendMerchantOrder string
doAction=SendMerchantInvoice ACTION: Send Merchant Invoice Copy to Customer email. doAction=SendMerchantInvoice string

Accepted date format is yyy-MM-dd HH:mm:ss. If the time is not provided, then it will default to midnight time.

Useful use cases for a courier company

1. Get all orders that are ready to ship (paid status)

Return all orders that are ready to ship. Use GET to retrieve the data.
EndPoint: https://api.website.world/webapps/api/basket?readyToShip=1

2. Update an existing order status as shipped (Courier approach)

Assuming you are a courier company, just provide only the minimal data to update your order. The data is provided as a "data" field, or as POST content in JSON format.

The UpdateShippingStatus action will update shipping dates and shipping status, and send a notification to the customer with the courier details, unless you also provide the parameter ?doNotSendNotification=1

EndPoint: https://api.website.world/webapps/api/order?doAction=UpdateShippingStatus

{
  "id": 26845824,
  "b_courier_ref": "999yourtrackcode999",
  "b_courier_url": "https://mycourier.com/mytrackingsystem?trackcode=999yourtrackcode999"
}

3. Update an existing order to shipped status

EndPoint: https://api.website.world/webapps/api/order

{
  "id": 26845824, 
  "b_shippedon": "2023-12-31 12:35:00",
  "b_status ": "Shipped"
}

Sample Output

Based on our endpoints, we can expect to receive a sample output data as below. A full same output is provided at the bottom of this page.

endpoint: The end point that is being used
resultCount: The total number of results returned
data: The actual data desried
success: true or false depicting the success of the query

{
       "b_cust_name": "my name",
       "b_ship_address": "123 Street",
       "b_ship_email": "name@myname.nz",
       "basketItems": [
           {
               "b_qty": 1.000,
               "pid": 2332685
   ...
           }
       ],
}

Data Dictionary - Order/Invoice Header

Field NameDescriptionData typeValidation Notes
b_id Unique Invoice Serial Number, aka ID Integer System generated, readonly
b_invoice_id Invoice Number Text Should be unique, defaults to b_id if null
b_created Draft order creation date Timestamp Automatically generated timestamp
b_closed The order date, when the draft order was submitted to be come a proper order.  Timestamp Required for submitted orders
b_stock_allocated True if stock counts have been allocated to this order, such that if cancelled stock allocation will be refreshed. Boolean True if allocated,
Null or false if not.
b_ip IP Address of customer Text Optional
b_user_agent Browser user agent data for debugging purposes, identifying robots Text Optional
b_is_domestic Tax status, Domestic or International Integer 0=International,1=Domestic
b_currency Currency of order Text 3 digit CCY code, eg NZD,USD,AUD etc
b_fx_rate The decimal multiplier from merchant base currency to currency selected. Decimal eg 0.90 NZD to AUD
cid Website ID. The Site ID is automatically assigned by CSV uploads and API connections.  Integer Readonly, Fkey to site ID
page All baskets are associated with the website page ID for the first product ordered. Some config settings exist to prevent split page orders. The Page ID is automatically assigned by CSV uploads and API connections.  Integer FKey to page
mbr_id Member ID / Customer ID Integer Foreign key to member table ID
b_affiliate Affiliate ID for affiliate style commissions Integer Foreign key to member table ID (Optional)
b_staff_id Sales person ID for POS users Integer Foreign key to member table ID (Optional)
b_shippingcalc Shipping Method Integer Foreign key to shipping calc table ID 
b_payment_method Payment method in human readable form, but is actually the payment type code. Text eg CashPOS,PayPal
b_payopid Payment method as ID reference, to the settings related to the payment method. Integer Foreign key to payment methods ID
b_promocode Promotional Code = Discount Code Text Code as per discounts/promotions end point (Optional)
b_wishlistid Related wishlist ID if this order originated from a wedding list type picklist. Integer Optional foriegn key to basket.b_id
b_total_discount The total discount as calculated by promotions  (excl sales tax) Decimal >= 0
b_total_vouchers The total of vouchers applied to this order. (Sales tax neutral) Decimal >= 0
b_total_shipping The total shipping fee (excl sales tax) Decimal >= 0
b_total_tax The total sales tax on the order (eg GST or VAT) Decimal >= 0
b_total_total The final total after considering all charges, discounts, vouchers, taxes, transaction fees, and post sale adjustments Decimal >= 0
b_total_transfee Optional transaction fee that may be applied to final invoice, for use of certain payment methods. Transaction fees do not increase tax. Decimal >= 0
b_total_savings Marketing savings, based on discounts or promotions on offer, but does not affect the total column, except where identified in b_total_discounts. Decimal >= 0
b_total_apishipping Location for storing any shipping fee calculated from a live pricing API. This value may differ from b_total_shipping if surcharges applied. Assumption is a GST exclusive fee. Decimal >= 0
b_total_paid Total amount of receipts received from the customer Decimal >= 0
b_total_refunds Total amount of any refunds given to the customer, in monetary form. (do not put discounts here) Decimal >= 0
b_total_deposit If customer is prepaying a deposit only, then this is the amount of deposit required, and customer will be expected to pay the remaining value of b_total_total - b_total_paid Decimal >= 0
b_total_adjustments Total of adjustments post sale, eg credits for returned items or fees for shipping overage fees.  Decimal Fees increase value. Credits decrease value.
b_total_adjustments_tax Sales Tax (GST or VAT) related to adjustments if any Decimal >=0
b_preadj_total The value of b_total_total, prior to post sale adjustments Decimal >=0
b_preadj_tax The value of b_total_tax, prior to post sale adjustments Decimal >=0
b_surcharge_fee A fee added to an order, usually via some sort of customisation script that calculates a fee using javascript or similar, or simply a POS surcharge on an order. Decimal
b_surcharge_reason Some text related to the surcharge, human readible, visible on invoice.  Text
b_total_qty Total of all line item quantities Decimal eg 4 = 2 line items of 2 quantity each
b_total_grams Total weight of all items in cart Integer eg 200 if each item is 50g x 4 items
b_item_count Number of line items Integer eg 2 = 2 lines items
b_cust_name Customer Personal Name (Billing Name) Text Required if not cash sale
b_cust_email Customer Email Text Email, Required if not cash sale
b_cust_phone Customer Phone (not validated format) Text
b_cust_company Customer Company name Text
b_cust_address Customer primary address (aka billing address) Text
b_cust_suburb Customer primary address (aka billing address) Text
b_cust_city Customer primary address (aka billing address) Text
b_cust_state Customer primary address (aka billing address) Text
b_cust_postcode Customer primary address (aka billing address) Text
b_cust_country Customer primary address (aka billing address) Text
b_ship_name Name of intended recipient Text
b_ship_email Email of intended recipient (Courier tracking sent here) Text Email
b_ship_phone Phone of intended recipient (provided to courier) Text
b_ship_company Company Name of delivery address optional Text
b_ship_address Delivery address (aka gift address) Text
b_ship_suburb Delivery address (aka gift address) Text
b_ship_city Delivery address (aka gift address), used for API shipping calc Text
b_ship_state Delivery address (aka gift address) Text
b_ship_postcode Delivery address (aka gift address), used for API shipping calc Text
b_ship_country Delivery address (aka gift address) Text
b_bill_email Email address of accounts department (optional extra full address format) Text Email 
b_cust_notes Notes given by customer as part of their order Text
b_notes_confidential Notes entered by merchant, that for for merchant / staff visibility only Text
b_courier_notes Notes given back to the customer about shipping status Text
b_courier_url A URL to a courier tracking site, that may or may not include a courier reference.. Presented to user as a clickable link Text https://....
b_courier_ref Courier tracking ticket number, for human viewing / readback, or for a human to copy and paste into a form Text
b_gift_message A message to be provided where applicable for gift stores. Text
b_custom_fields JSON data structure of any additional custom questions asked during checkout. Text
b_confirmtermsandconditions If T&C exist, this will be T Char(1) T or NULL
b_reminderperiod If customer wishes to be reminded on an aniversary, then this is when they will be reminded (interval from the last order) Interval
b_remindernotes If customer wishes to be reminded on an aniversary, then notes to themselves, perhaps persons name, or product serial number. Text
b_reminderdue If customer wishes to be reminded on an aniversary, then this is when they will be reminded next. Timestamp
b_paidon Time once order payment was completed in full. Null if partially paid. Primary indicator of fully paid orders Timestamp
b_readytoship Timestamp indicating an order has been picked/packed, and is ready to ship or collect by customer. Timestamp
b_shippedon Time when order was marked as shipped. Primary indicator that an order has been collected or shipped or taken, essentially completing the order status. Timestamp
b_pref_delivery_time Customers preferred delivery time, that can be free text in some situations Text
b_pref_delivery_timestamp Customers target delivery time in a timestamp format, that is better suited to sorting and filtering. Timestamp
b_cancelled Time of cancellation if cancelled. Primary indicator of cancellation Timestamp
b_paycustcode Customers may provide their account number when checking out, rather than payment. (Not validated) Text
b_paypurchaseorder Customers may provide their own purchase order number when checking out, for future reconcilation when the goods are received and documentation accounted for. Text
b_points_redeemed Loyalty points redeemed for this order (if submitted) Decimal
b_points_earned Loyalty points earned from this order (if submitted) Decimal
b_value_redeemed The monetary value of points redeemed on this order, that would have adjusted the total due of the order. Decimal
b_points_earned_affiliate Loyalty points earned by an affiliate who referred the sale. Decimal
b_paymentsummary Human readible payment summary Text
b_shopchannel Indicates Website or POS, or Market place where order originated Text
b_wishlist_title Only used if order is a wishlist Text
b_type Identifies the type of orders that were saved prior to submitting them, eg wishlists or saved orders.  Text eg Wishlist,Saved
b_customer_savedon When customer saved this order / wishlist. Timestamp
b_cancelled_by_customer If customer cancelled this order, then when Timestamp
b_booking_start The booking time Timestamp
b_booking_finish The end booking time, may be selectable for rental items, but otherwise is the booking start plus the duration Timestamp
b_booking_duration The total duration of the order, from a pricing perspective. Interval
b_booking_resourceid The staff member or room assigned to the booking (resource used by all products in the order) Integer Fkey to booking resource ID
b_version If an order is re opened after being closed, then the version number will increment and affect the invoice ID Integer
b_status The status of an order, human readible.  Text
b_status_updated The timestamp when the order status was last updated Timestamp
b_repeat_interval For repeating orders (aka subscriptions) this is the repeat interval Interval
b_repeat_target The target date for the draft order to be closed, and start the next draft order. Allows users to skip a repeatition.  Timestamp
b_repeated_from_bid The last basket ID in the repeating order chain. Integer Fkey to basket b_id
b_address_quality API results from address validation checker service, if enabled Text
b_shippingbreakdown An explanation of shipping calculated by live pricing API Text

Data Dictionary (Item Lines)

Field NameDescriptionData typeValidation Notes
b_id Relates item lines to the order header record Integer FKey to basket b_id
bi_id Unique Invoice Line Serial Number (readonly) Integer (readonly)
pid Product ID (variant option specific) Integer FKey to product id
p_parentpid Product ID (to the master product if a variant, otherwise same as PID) Integer FKey to product id
b_qty Quantity of product ordered Decimal 3 decimal places ok
b_unit_price Unit price of product, GST exclusive, in desired CCY Decimal
bi_priceprediscount Presale RRP unit price of product, GST exclusive, in desired CCY Decimal
bi_disc_amt Value of the discount, per order line, GST excl, in desired CCY Decimal
bi_tax_amt Sales tax total for line. Decimal
bi_disc_amt_pos POS can override the discounts. Some users have used negative discounts, but this is not desired. Decimal >=0 
bi_custom_total Decimal
bi_line_total The line total considering quantity and discounts, (but excluding tax) Decimal
b_option Style or custom option for product, relates to p_style or p_option Text
b_size Size of product, relates to p_size or p_option Text
b_colour Colour of product, relates to p_colour or or p_option Text
b_optext If product supports custom text option, e.g. insignia name Text
bi_custom_fields If product supports unlimited customisation options, then saved in JSON format here. eg customise your burger Text JSON
bi_detail Human readable text, typically is the product name. Text
bi_message System generated message related to order line error, or delays in stock availability or back order. Text
bi_discountmessage System generated human readible message to explain the discount applied Text
b_bookingid Connects this line item to it's related booking reference. This could be a common booking for the whole order with a single resource, or multiple bookings per order, to associate this line item with a specific hire item instance Integer Fkey to booking ID
b_eventattendeeid Event attendee ID record. If multiple lines have the same attendee record, then the attendee record has the total seat count, and the b_qty is the number of seats related to just this item line. Often split when purchasing different price tickets for children in a family. Integer Fkey to event attendee ID
b_bookingsummary Human readible summary of booking details for this line item. Text
bi_partof_bi When products are assemblies of other products, this may indicate that the item line is a part of another basket line, where the merchant requires the explosion of a recipe into it's parts. Integer Fkey to basket item bi_id
bi_hold Some item lines can be held back from shipping API's, so that partial orders can be shipped.  Boolean
bi_created Timestamp when this order line was created, most important for adjustments, as these happen after basket.b_closed Timestamp
bi_adjusted_from_bi_id Indicates a post sale adjustment of an order. eg stock movement for warranty or replacement items. Integer Fkey to basket item bi_id
bi_adjust_type Reason for adjustment Text