Orders API

Version: 1.0

Table of contents

• Table of contents
• Overview
• Concepts and terminology
  • Order identifiers
  • Order lifecycle state
  • Payment status
  • Fulfillment status
  • Cancellation reasons
• Capabilities
• Business and API rules
• API operations
  • List orders
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
    • Examples
  • Count orders
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Retrieve an order
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Confirm an order
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Close an order
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Reopen a closed order
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Cancel an order
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Update an order
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Add order tags
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Delete order tags
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
  • Assign order handling
    • Purpose
    • Endpoint
    • Input
    • Output
    • Constraints
• Data definitions
  • Core Order fields
  • Amount and weight fields
  • Addresses
  • Customer
  • Line items
  • Discounts, shipping, tax, refunds, and transactions
  • Fields with ambiguous source definitions
• Search, filter, sort, and pagination
• Permissions and limitations
• Errors and exceptions
• Usage guidance for AI

Overview

An Order represents a customer's request to purchase one or more products from a shop. This AI-facing Orders API specification supports reading and filtering orders, counting orders, retrieving a specific order, updating a limited set of attributes, changing order lifecycle state, managing tags, cancelling and refunding, and assigning advanced order-processing responsibility.

Creating orders is explicitly outside the AI scope of this specification. AI agents must not call or propose POST /com/orders.json, even when their credential has com.write_orders.

Concepts and terminology

Order identifiers

Field	Meaning
id	Numeric identifier used in API paths such as /com/orders/{order_id}.json.
order_number	Identifier intended for the merchant and customer. It is distinct from the API id.
name	Display name generated from the order number plus the merchant's configured prefix and suffix. The API can also set this field to a string value.
number	Position of the order in the shop's order count.
token	Unique value used when referencing the order.
cart_token	Identifier of the cart associated with the order.
checkout_token	Identifier of the checkout associated with the order.

Use id, not order_number, name, or number, as {order_id} in documented API paths.

Order lifecycle state

Concept	Documented values or meaning
Confirmation	confirmed_at records when the order was confirmed. confirmed_status is shown as unconfirmed before confirmation. The source does not enumerate every possible confirmed_status value.
Closure	closed_at is the close timestamp or null. closed_status is shown as unclosed before closure. A closed order has no more work to perform because its items have been fulfilled or refunded.
Cancellation	cancelled_at is the cancellation timestamp or null. cancelled_status is shown as uncancelled before cancellation and cancelled in a cancellation example.

Payment status

The source states that financial_status can be set only when an order is created. Order creation is outside this AI specification, so agents should treat this field as read-only here. Documented values are:

Value	Meaning
pending	Payment is pending and might still fail.
authorized	Payment has been authorized.
partially_paid	Order has been partially paid.
paid	Payment has been recorded as paid.
partially_refunded	Payment has been partially refunded.
refunded	Payment has been refunded.
voided	Payment has been voided.

One legacy response example contains partiallypaid without an underscore, while the property definition and list filter use partially_paid. The source does not explain whether partiallypaid is a valid value or an example defect; do not rely on it without separate confirmation.

Fulfillment status

The Order resource documents these fulfillment_status values:

Value	Meaning
null	No line item has been fulfilled.
partial	At least one line item has been fulfilled.
fulfilled	Every line item has been fulfilled.
restocked	Every line item has been restocked and the order cancelled.

The list endpoint uses different filter terms: unshipped, shipped, and partial. Do not substitute resource values for filter values.

Cancellation reasons

Value	Meaning
customer	Customer changed or cancelled the order.
fraud	Order was fraudulent.
inventory	Items were not available in inventory.
declined	Payment was declined.
other	Cancellation reason is not represented by another value.

Capabilities

The documented API can:

• List orders with server-side filters, field selection, sorting, and page-based pagination.
• Count all orders or count cancelled orders using the documented example.
• Retrieve an order by its API id.
• Confirm, close, reopen, or cancel an order.
• Record a cancellation refund by amount or by a structured refund object.
• Update note and note_attributes using the documented update examples.
• Add or remove tags.
• Assign users, groups, and a location for advanced order processing.

The documented API does not provide an endpoint that deletes the Order resource. A DELETE endpoint exists only for removing tags. Although the legacy introduction says orders can be deleted, no order-deletion operation or contract is documented.

Create Order is intentionally excluded from the AI capability set. Its endpoint, request contract, and examples are not included in this specification.

Business and API rules

• financial_status is creation-only in the source and is therefore read-only within this AI specification.
• The API can update only a limited set of Order attributes. The documented update examples cover note and note_attributes.
• Line items and line-item quantities cannot be changed through the Order update operation.
• Orders created through Haravan POS might not have an attached customer. Consumers must handle customer: null.
• billing_address can be absent when an order does not require a payment method.
• shipping_address can be absent when an order does not require shipping.
• source_name is creation-only in the source and cannot be changed through the supported AI operations.
• Tags are stored as a comma-separated string. Each individual tag is limited to 40 characters.
• total_price and total_tax are documented as positive values.
• total_weight is not adjusted when items are removed from the order.
• A gift-card line item is not taxed and is not included in shipping charges.
• A closed order is described as having no remaining work because all items have been fulfilled or refunded.
• Assignment is documented only for shops using advanced order processing.

API operations

List orders

Purpose

Use this operation to retrieve multiple orders and narrow the result on the server. Prefer it over downloading all orders and filtering locally.

Endpoint

GET https://apis.haravan.com/com/orders.json

Input

All inputs are query parameters.

Parameter	Type	Required	Description
ids	string	No	Comma-separated API order IDs.
limit	integer	No	Results per page. Default 50; maximum 50.
page	not specified	No	Page to return.
since_id	not specified	No	Return results after the specified API ID.
created_at_min	ISO 8601 timestamp	No	Orders created after the timestamp.
created_at_max	ISO 8601 timestamp	No	Orders created before the timestamp.
updated_at_min	ISO 8601 timestamp	No	Orders updated after the timestamp.
updated_at_max	ISO 8601 timestamp	No	Orders updated before the timestamp.
processed_at_min	ISO 8601 timestamp	No	Orders imported after the timestamp.
processed_at_max	ISO 8601 timestamp	No	Orders imported before the timestamp.
financial_status	string	No	pending, paid, partially_paid, refunded, voided, or partially_refunded. The list filter does not document authorized.
fulfillment_status	string	No	unshipped, shipped, or partial.
status	string	No	open, closed, cancelled, or any. any includes archived orders.
fields	string	No	Comma-separated fields to include in the response.
order	string	No	Sort by created_at or updated_at, followed by asc or desc.

Output

Returns HTTP 200 OK with an orders array. Each entry is an Order object. When fields is supplied, the examples show only the selected fields.

Constraints

• Page size cannot exceed 50.
• Only created_at and updated_at are documented as sortable.
• The source does not define a default sort order.

Examples

GET /com/orders.json?page=1
GET /com/orders.json?updated_at_min=2021-01-04T00:00:00.000Z
GET /com/orders.json?fields=id,name,created_at
GET /com/orders.json?since_id=1138637000
GET /com/orders.json?order=created_at%20desc

Count orders

Purpose

Use this operation when only the number of matching orders is needed and the Order objects themselves are unnecessary.

Endpoint

GET https://apis.haravan.com/com/orders/count.json

Input

The source demonstrates no query parameter for the total count and status=cancelled for a cancelled-order count. It does not specify whether every list filter is supported by the count endpoint.

Output

Returns HTTP 200 OK with a numeric count.

{
  "count": 500
}

Constraints

Do not assume unsupported list filters also work for this endpoint.

Retrieve an order

Purpose

Use this operation when the API id of a specific order is known and the full Order resource is required.

Endpoint

GET https://apis.haravan.com/com/orders/{order_id}.json

Input

order_id is the Order API id. The examples use a numeric value.

Output

Returns HTTP 200 OK with an order object.

Constraints

The source does not document the error response for an unknown order_id.

Confirm an order

Purpose

Use this operation to confirm an existing order.

Endpoint

POST https://apis.haravan.com/com/orders/{order_id}/confirm.json

Input

order_id is the Order API id. The documented body is an empty JSON object.

{}

Output

Returns HTTP 200 OK with the updated order object.

Constraints

The source does not define eligible states, repeat-call behavior, or confirmation-specific errors.

Close an order

Purpose

Use this operation when an order has no more work to perform because all items have been fulfilled or refunded.

Endpoint

POST https://apis.haravan.com/com/orders/{order_id}/close.json

Input

order_id is the Order API id. The documented body is {}.

Output

Returns HTTP 200 OK with the updated order object.

Constraints

The source describes what a closed order means but does not document server validation for incomplete orders.

Reopen a closed order

Purpose

Use this operation to reopen an order that is closed.

Endpoint

POST https://apis.haravan.com/com/orders/{order_id}/open.json

Input

order_id is the Order API id. The documented body is {}.

Output

Returns HTTP 200 OK with the updated order object.

Constraints

The source does not document behavior when the order is not closed.

Cancel an order

Purpose

Use this operation to cancel an order. It can also record a refund, optionally restock items, send a cancellation email, and control fulfillment cancellation behavior.

Endpoint

POST https://apis.haravan.com/com/orders/{order_id}/cancel.json

Input

Input	Type	Required in source	Description
order_id	string in source; examples are numeric	Yes	API order ID in the path.
amount	string	No	Amount to refund. Haravan attempts the refund depending on transaction status.
email	boolean	No; default false	Send a cancellation email to the customer.
reason	string	Marked required	customer, inventory, fraud, declined, or other.
refund	object	No	Structured refund with line items and transactions for more complex cases.
restock	boolean	No; default false	Restock refunded items.
note	string	No	Note attached to the refund.
ignore_cancel_fulfillment	boolean	No; default false	Ignore fulfillment cancellation when set.

Example using an amount:

{
  "amount": "520000",
  "reason": "customer",
  "restock": true,
  "email": true,
  "note": "Customer made a mistake",
  "ignore_cancel_fulfillment": true
}

Example using a structured refund:

{
  "reason": "customer",
  "note": "Customer made a mistake",
  "refund": {
    "refund_line_items": [
      {
        "line_item_id": 1315883217,
        "quantity": 1
      }
    ],
    "transactions": [
      {
        "amount": "300000",
        "kind": "refund"
      }
    ]
  }
}

Output

Returns HTTP 200 OK with the updated order. Refund examples show refunds, refund transactions, cancel_reason, cancelled_at, and an updated financial_status such as partially_refunded.

Constraints

• If the original transaction was not made in Haravan, Haravan records a refund through a manual gateway but does not refund the customer externally.
• The source marks reason as required but also shows an empty-body cancellation example. This is unresolved source inconsistency. Provide a documented reason rather than assuming omission is supported.
• Complex refund behavior is defined by the Refund API; this page does not reproduce its complete contract.

Update an order

Purpose

Use this operation only for the limited mutable attributes documented by the source.

Endpoint

PUT https://apis.haravan.com/com/orders/{order_id}.json

Input

The documented request envelope is order. The examples update note or replace note_attributes:

{
  "order": {
    "id": 1225418252,
    "note": "Customer contacted us about a custom engraving"
  }
}

{
  "order": {
    "id": 1225418252,
    "note_attributes": [
      {
        "name": "colour",
        "value": "red"
      }
    ]
  }
}

Output

Returns HTTP 200 OK with the updated order object.

Constraints

• Line items and their quantities cannot be changed.
• The source does not provide a complete list of mutable attributes. Do not assume an output field is writable merely because it appears in a response.
• financial_status and source_name are documented as creation-only and cannot be changed by the supported update operation.

Add order tags

Purpose

Use this operation to add tags while preserving tags that are not named in the request.

Endpoint

POST https://apis.haravan.com/com/orders/{order_id}/tags.json

Input

{
  "tags": "a1,a2"
}

Output

Returns HTTP 200 OK with the resulting comma-separated tags string. The example adds a1,a2 to existing VIP and returns VIP,a1,a2.

Constraints

• Each tag is limited to 40 characters.
• The legacy example labels the call as GET, but the operation declaration and endpoint inventory specify POST. The source does not explain the mismatch; use the declared POST operation.

Delete order tags

Purpose

Use this operation to remove the tags named in the request. It does not delete the Order resource.

Endpoint

DELETE https://apis.haravan.com/com/orders/{order_id}/tags.json

Input

{
  "tags": "a1,a2"
}

Output

Returns HTTP 200 OK with the remaining comma-separated tags string. The example removes a1,a2 and returns VIP.

Constraints

The source does not document behavior when a requested tag is not present.

Assign order handling

Purpose

Use this operation to assign handling users, user groups, and a location when advanced order processing is enabled.

Endpoint

POST https://apis.haravan.com/com/orders/{order_id}/assign.json

Input

{
  "user_ids": [200001038919],
  "group_user_ids": [0],
  "location_id": 876530
}

The source does not document whether each array can contain multiple values, what group_user_ids: [0] represents, or which fields are individually required.

Output

Returns HTTP 200 OK with the updated order. The example includes assignment fields such as assigned_location_id, assigned_location_name, assigned_location_at, and order_processing_status.

Constraints

• This operation is documented only for advanced order processing.
• Eligibility, assignment validation, and permission errors are not documented.

Data definitions

Core Order fields

Field	Type in source	Definition and constraints
id	number	API identifier for the Order.
name	string	Merchant/customer display name; generated from number plus configured prefix/suffix unless explicitly set by API.
number	number	Position in the shop's order count.
order_number	string	Merchant/customer identifier, distinct from API id.
email	string	Customer email address.
contact_email	string	Contact email of the buyer. The source does not explain its relationship to email.
note	string	Optional note attached by the merchant.
note_attributes	array	Additional name/value details displayed in the order's Additional details section.
tags	string	Comma-separated tags; each tag is at most 40 characters.
currency	string	Three-letter ISO 4217 shop currency code.
created_at	string	Creation timestamp in ISO 8601 format.
updated_at	string	Last-update timestamp in ISO 8601 format.
confirmed_at	string or null	Confirmation timestamp in ISO 8601 format.
closed_at	string or null	Closure timestamp in ISO 8601 format.
cancelled_at	string or null	Cancellation timestamp in ISO 8601 format.
cancel_reason	string or null	Documented cancellation-reason enum.
financial_status	string	Payment status; creation-only according to the field definition.
fulfillment_status	string or null	Overall fulfillment state.
processing_method	string or null	checkout, direct, manual, or offsite.
source_name	string	Creation-only order source with protected Haravan channel values.
gateway	string	Payment gateway name recorded on the order.
gateway_code	string	Unique identifier of the recorded payment gateway.
user_id	number	Haravan POS user who processed the order, when applicable.
location_id	number	Physical location where the order was processed.

The source examples for these timestamps use ISO 8601 values ending in Z, which denotes UTC (for example, 2021-05-13T07:29:20.1Z). The field descriptions specify ISO 8601 but do not explicitly guarantee the timezone or offset used for every response. Timestamp filter examples also use a Z UTC suffix. To match the documented examples, send filter timestamps in ISO 8601 UTC form with Z; do not assume an undocumented local timezone conversion.

Amount and weight fields

Field	Type	Meaning
subtotal_price	number	Price after discounts and before shipping, duties, taxes, and tips.
total_discounts	number	Total discounts in shop currency.
total_line_items_price	number	Sum of line-item prices in shop currency.
total_price	number	Sum of line-item prices, discounts, shipping, taxes, and tips; documented as positive.
total_tax	number	Sum of taxes in shop currency; documented as positive.
total_weight	number	Sum of line-item weights in grams; not adjusted when items are removed.
taxes_included	source says string	Whether taxes are included in the subtotal; documented values are true and false. The declared type conflicts with the boolean-like values.

Addresses

billing_address and shipping_address contain address fields including address1, address2, city, company, country, country_code, first_name, last_name, latitude, longitude, name, phone, province, province_code, and zip. Response examples also include Haravan-specific district, district_code, ward, and ward_code.

Billing address is optional when no payment method is required. Shipping address is optional when no shipping is required.

Customer

customer contains customer information and can be null, especially for orders created through Haravan POS. Consumers must not depend on its presence. Use the Customer API for the customer contract.

Line items

Important documented line-item fields include:

Field	Meaning
id	Line-item identifier.
product_id	Product identifier; can become null if the original product is later deleted.
variant_id	Product-variant identifier.
quantity	Purchased quantity.
fulfillable_quantity	quantity - max(refunded_quantity, fulfilled_quantity) - pending_fulfilled_quantity.
price	Price before discounts.
total_discount	Discount applied to the line item; it is not subtracted from price.
grams	Weight in grams.
fulfillment_service	manual or provider name.
fulfillment_status	Source lists fulfilled, null, or partial for a line item.
requires_shipping	Whether shipping is required.
sku	Stock keeping unit.
title	Product title.
variant_title	Variant title.
vendor	Supplier name.
name	Product-variant name.
gift_card	Gift-card indicator; gift cards are not taxed or included in shipping charges.
taxable	Whether the line item is taxable.
tax_lines	Taxes applicable to the line item.

Response examples contain additional line-item fields such as barcode, properties, applied_discounts, image, product_exists, not_allow_promotion, and ma_cost_amount, but the source does not fully define their contract.

Discounts, shipping, tax, refunds, and transactions

• discount_codes is an array. Documented fields include code, amount, and type; documented type values are percentage, shipping, and fixed_amount, with fixed_amount identified as the default.
• shipping_lines is an array of shipping methods with code, price, source, title, and optionally tax_lines. The legacy property heading is corrupted, but response examples consistently use shipping_lines.
• tax_lines contains price, rate, and title for applicable taxes.
• refunds contains refunds associated with the order. The legacy property section incorrectly places a refunds example under the referring_site heading, so the definition of referring_site is not reliable in that section.
• transactions contains transaction records. Use the Transactions API for the complete transaction contract.
• fulfillments contains fulfillment records associated with the order.

Fields with ambiguous source definitions

• The legacy browser_ip property description says whether the customer accepted marketing, but response examples separately contain both browser_ip and buyer_accepts_marketing. The exact browser_ip definition is therefore not reliable in the source.
• The legacy referring_site property block contains a refunds example rather than a referring-site definition.
• taxes_included is labeled as a string but documented with boolean values.
• Response examples include many additional fields without definitions. Presence in an example does not establish writability, enum values, or business behavior.

Search, filter, sort, and pagination

• Use ids to request known API IDs in one list call.
• Use created_at_min/created_at_max, updated_at_min/updated_at_max, and processed_at_min/processed_at_max for server-side time ranges.
• Use financial_status, fulfillment_status, or status for documented state filtering.
• Use fields to reduce the response when only specific fields are needed.
• Pagination is page-based through page; limit defaults to 50 and cannot exceed 50.
• Sort only by the documented fields created_at and updated_at, using asc or desc.
• The source does not document cursor pagination, a total-page response field, or a default sort order.

Permissions and limitations

• Read operations require com.read_orders.
• Write operations require com.write_orders.
• Possession of com.write_orders does not place Create Order within the AI capability set. AI agents must not call POST /com/orders.json.
• All Haravan APIs are subject to platform rate limits, but this Orders source does not state the numeric threshold. See API Rate Limits.
• The update operation cannot change line items or quantities.
• No endpoint for deleting the Order resource is documented.
• Assignment is limited to advanced order processing.
• Historical data limits are not documented by this source.

Errors and exceptions

The source documents successful 200 OK responses for the reads and actions included here. It does not provide structured error payloads or operation-specific error status codes.

Callers must still account for these documented failure conditions or uncertainties:

• Missing or insufficient read/write scope.
• Unknown order_id.
• Invalid enum or filter value.
• limit greater than 50.
• Attempt to update immutable or unsupported fields, including line items and quantities.
• Invalid order state for a lifecycle action; exact state validation is not documented.
• Invalid refund or transaction data; use the Refund API contract for complex refunds.
• Advanced assignment used when the feature is unavailable.

The exact HTTP status and error body for these cases are not specified in this source and must not be invented.

Usage guidance for AI

• Use the API id for {order_id}; do not substitute order_number, name, or number.
• Never call or propose POST /com/orders.json; Create Order is outside the AI scope even when com.write_orders is available.
• Use GET /com/orders/count.json when only a count is needed.
• Use server-side filters, field selection, sorting, and pagination instead of retrieving all orders for local processing.
• Use only the documented list filter values. In particular, distinguish fulfillment filter values from the resource's fulfillment-status values.
• Treat customer, billing_address, and shipping_address as optional.
• Treat financial_status as read-only in this AI specification.
• Do not attempt to update line items or quantities through the Order update endpoint.
• Use the dedicated tag endpoints for tag changes.
• Do not interpret DELETE /tags.json as Order deletion.
• Prefer a documented cancellation reason because the source conflicts on whether omission is allowed.
• For complex cancellation refunds, use the Refund API definitions rather than inferring refund behavior from examples alone.
• Treat fields shown only in response examples as read-only or unknown unless another source explicitly documents them as writable.
• When the source does not define validation, state transitions, errors, or capabilities, treat them as unknown rather than assuming conventional behavior.